@kelviq/mcp-server 0.3.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 (103) hide show
  1. package/README.md +37 -30
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +31 -10
  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 +84 -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 +134 -63
  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 +109 -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/prompts/index.d.ts +2 -0
  62. package/dist/prompts/index.js +107 -0
  63. package/dist/prompts/index.js.map +1 -0
  64. package/dist/schemas/kelviq.d.ts +30 -0
  65. package/dist/schemas/kelviq.js +50 -0
  66. package/dist/schemas/kelviq.js.map +1 -1
  67. package/dist/server.js +15 -3
  68. package/dist/server.js.map +1 -1
  69. package/dist/tools/checkout.js +2 -1
  70. package/dist/tools/checkout.js.map +1 -1
  71. package/dist/tools/customers.js +2 -0
  72. package/dist/tools/customers.js.map +1 -1
  73. package/dist/tools/docs.js +2 -0
  74. package/dist/tools/docs.js.map +1 -1
  75. package/dist/tools/entitlements.js +1 -0
  76. package/dist/tools/entitlements.js.map +1 -1
  77. package/dist/tools/features.js +4 -0
  78. package/dist/tools/features.js.map +1 -1
  79. package/dist/tools/licenses.js +3 -0
  80. package/dist/tools/licenses.js.map +1 -1
  81. package/dist/tools/offerings.js +1 -0
  82. package/dist/tools/offerings.js.map +1 -1
  83. package/dist/tools/plan-entitlements.js +4 -0
  84. package/dist/tools/plan-entitlements.js.map +1 -1
  85. package/dist/tools/plan-files.js +3 -0
  86. package/dist/tools/plan-files.js.map +1 -1
  87. package/dist/tools/plans.js +8 -0
  88. package/dist/tools/plans.js.map +1 -1
  89. package/dist/tools/portal.js +1 -0
  90. package/dist/tools/portal.js.map +1 -1
  91. package/dist/tools/product-files.js +2 -0
  92. package/dist/tools/product-files.js.map +1 -1
  93. package/dist/tools/product-settings.js +2 -0
  94. package/dist/tools/product-settings.js.map +1 -1
  95. package/dist/tools/products.js +5 -0
  96. package/dist/tools/products.js.map +1 -1
  97. package/dist/tools/promotions.js +1 -0
  98. package/dist/tools/promotions.js.map +1 -1
  99. package/dist/tools/subscriptions.js +5 -1
  100. package/dist/tools/subscriptions.js.map +1 -1
  101. package/dist/tools/usage.js +1 -0
  102. package/dist/tools/usage.js.map +1 -1
  103. package/package.json +1 -1
@@ -0,0 +1,150 @@
1
+ ---
2
+ title: "Apply a discount code at checkout"
3
+ slug: "checkout/apply-a-discount-code"
4
+ section: "checkout"
5
+ description: "Let customers enter a discount code or pre-apply one to a Kelviq checkout"
6
+ ---
7
+ Kelviq can show a discount-code field at checkout or apply a known code before the checkout page opens. Use the first option for general promotions and the second for targeted campaigns, partner offers, or customer-specific links.
8
+
9
+ ## Before you start
10
+
11
+ Create the code in **Product Catalog → Discounts** and check that it:
12
+
13
+ - is active and has not expired;
14
+ - has not reached its redemption limit;
15
+ - applies to the selected product and plan; and
16
+ - uses the same currency as the price when it is a fixed-amount discount.
17
+
18
+ [Learn how to create and restrict a discount →](/product-catalog/discounts)
19
+
20
+ ## Let the customer enter a code
21
+
22
+ When creating a checkout session through the API, set `discountsEnabled` to `true`. This shows the discount-code field so the customer can enter an eligible code.
23
+
24
+ ```json
25
+ {
26
+ "planIdentifier": "pro",
27
+ "chargePeriod": "MONTHLY",
28
+ "customerId": "cust_789",
29
+ "successUrl": "https://example.com/checkout/success",
30
+ "discountsEnabled": true
31
+ }
32
+ ```
33
+
34
+ `discountsEnabled` defaults to `true`. Set it to `false` only when you want to hide discount-code entry for that session.
35
+
36
+ ## Pre-apply a code with the Checkout API
37
+
38
+ Pass the code as `discountCode` in the JSON request body. Kelviq validates it while creating the checkout session. If the code is inactive, expired, or not valid for the selected plan, the request fails instead of creating a session with the wrong price.
39
+
40
+ ```bash cURL
41
+ curl --request POST \
42
+ --url https://sandboxapi.kelviq.com/api/v1/checkout/ \
43
+ --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
44
+ --header "Content-Type: application/json" \
45
+ --data '{
46
+ "planIdentifier": "pro",
47
+ "chargePeriod": "MONTHLY",
48
+ "customerId": "cust_789",
49
+ "successUrl": "https://example.com/checkout/success",
50
+ "discountsEnabled": true,
51
+ "discountCode": "LAUNCH20"
52
+ }'
53
+ ```
54
+
55
+ ```javascript Node.js
56
+ const response = await fetch("https://sandboxapi.kelviq.com/api/v1/checkout/", {
57
+ method: "POST",
58
+ headers: {
59
+ Authorization: `Bearer ${process.env.KELVIQ_SANDBOX_SERVER_API_KEY}`,
60
+ "Content-Type": "application/json",
61
+ },
62
+ body: JSON.stringify({
63
+ planIdentifier: "pro",
64
+ chargePeriod: "MONTHLY",
65
+ customerId: "cust_789",
66
+ successUrl: "https://example.com/checkout/success",
67
+ discountsEnabled: true,
68
+ discountCode: "LAUNCH20",
69
+ }),
70
+ });
71
+
72
+ if (!response.ok) {
73
+ throw new Error(await response.text());
74
+ }
75
+
76
+ const { checkoutUrl } = await response.json();
77
+ ```
78
+
79
+ ```python Python
80
+ import os
81
+ import requests
82
+
83
+ response = requests.post(
84
+ "https://sandboxapi.kelviq.com/api/v1/checkout/",
85
+ headers={
86
+ "Authorization": f"Bearer {os.environ['KELVIQ_SANDBOX_SERVER_API_KEY']}",
87
+ "Content-Type": "application/json",
88
+ },
89
+ json={
90
+ "planIdentifier": "pro",
91
+ "chargePeriod": "MONTHLY",
92
+ "customerId": "cust_789",
93
+ "successUrl": "https://example.com/checkout/success",
94
+ "discountsEnabled": True,
95
+ "discountCode": "LAUNCH20",
96
+ },
97
+ )
98
+ response.raise_for_status()
99
+
100
+ checkout_url = response.json()["checkoutUrl"]
101
+ ```
102
+
103
+ A successful request returns the hosted checkout URL:
104
+
105
+ ```json
106
+ {
107
+ "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
108
+ "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
109
+ }
110
+ ```
111
+
112
+ Redirect the customer to `checkoutUrl`. Before completing payment, confirm that checkout shows the code, adjusted price, currency, and billing period you expect.
113
+
114
+ ## Pre-apply a code in a static checkout link
115
+
116
+ For a static product checkout link, use the snake-case `discount_code` query parameter:
117
+
118
+ ```text
119
+ https://www.kelviq.com/buy/123e4567-e89b-12d3-a456-426614174000/?plan_identifier=pro&charge_period=MONTHLY&discounts_enabled=true&discount_code=LAUNCH20
120
+ ```
121
+
122
+ Use the product UUID shown in the Kelviq dashboard. URL-encode the code if it contains spaces or reserved characters.
123
+
124
+ The names are different by design: use `discountCode` in an API JSON body and `discount_code` in a static checkout URL.
125
+
126
+ [See all static checkout URL parameters →](/checkout/static-checkout-url)
127
+
128
+ ## Test the integration
129
+
130
+ Test the complete flow in sandbox before using a production code:
131
+
132
+ 1. Create a sandbox discount and an eligible product price.
133
+ 2. Create the checkout session with the matching sandbox API key.
134
+ 3. Open the returned checkout URL.
135
+ 4. Confirm the original price, discount, tax, and final total.
136
+ 5. Complete payment with a sandbox payment method and check the resulting order.
137
+
138
+ Do not test a small live charge on your own card. Repeated self-payments can cause the card to be blocked. Use sandbox, or use a valid 100% discount when you must inspect the production checkout without collecting a real payment.
139
+
140
+ ## Troubleshooting
141
+
142
+ | Problem | Check |
143
+ | --- | --- |
144
+ | Checkout creation fails | Confirm the code is active, unexpired, within its redemption limit, and valid for the selected plan. |
145
+ | Fixed discount is rejected | Confirm the discount currency matches the selected price currency. |
146
+ | The code field is missing | Set `discountsEnabled` or `discounts_enabled` to `true`, depending on how you create checkout. |
147
+ | The code is not pre-applied | Use `discountCode` for the API or `discount_code` for a static link. |
148
+ | Sandbox code is not found in production | Recreate the discount in production; the two environments do not share data. |
149
+
150
+ For the complete request and response schema, see [Create a checkout session API reference](/api-reference/checkout/create-a-checkout-session).
@@ -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)