@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.
- package/README.md +37 -30
- package/dist/config.d.ts +5 -0
- package/dist/config.js +31 -10
- 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 +84 -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 +134 -63
- 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 +109 -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/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -0
- package/dist/schemas/kelviq.js +50 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +15 -3
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +3 -0
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +8 -0
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.js +1 -0
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +5 -0
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +5 -1
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- 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
|
-
|
|
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)
|