@kelviq/mcp-server 0.2.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/LICENSE +21 -0
- package/README.md +322 -0
- package/dist/config.d.ts +16 -0
- package/dist/config.js +45 -0
- package/dist/config.js.map +1 -0
- package/dist/docs/README.md +128 -0
- package/dist/docs/api-reference/authentication.md +41 -0
- package/dist/docs/backend-integration/node-sdk.md +1040 -0
- package/dist/docs/backend-integration/python-sdk.md +1198 -0
- package/dist/docs/changelog/app.md +80 -0
- package/dist/docs/changelog/checkout-api.md +59 -0
- package/dist/docs/changelog/js-promotions-ui.md +14 -0
- package/dist/docs/changelog/js-sdk.md +281 -0
- package/dist/docs/changelog/node-sdk.md +378 -0
- package/dist/docs/changelog/python-sdk.md +456 -0
- package/dist/docs/changelog/react-sdk.md +580 -0
- package/dist/docs/checkout/checkout-configuration.md +434 -0
- package/dist/docs/coustomers-management/overview.md +111 -0
- package/dist/docs/customer-portal/overview.md +81 -0
- package/dist/docs/frontend-integration/js-sdk.md +676 -0
- package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
- package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
- package/dist/docs/frontend-integration/react-sdk.md +1187 -0
- package/dist/docs/frontend-integration/react-ui.md +771 -0
- package/dist/docs/getstarted/fees.md +160 -0
- package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
- package/dist/docs/getstarted/merchant-of-record.md +64 -0
- package/dist/docs/getstarted/review-process.md +190 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
- package/dist/docs/guides/subscription-integration.md +291 -0
- package/dist/docs/guides/webhooks.md +963 -0
- package/dist/docs/legal/approved-prohibited-policy.md +252 -0
- package/dist/docs/legal/buyer-terms.md +177 -0
- package/dist/docs/legal/compliant-user-flow.md +216 -0
- package/dist/docs/legal/master-service-agreement.md +404 -0
- package/dist/docs/legal/payment-flow-diagram.md +188 -0
- package/dist/docs/legal/seller-terms.md +169 -0
- package/dist/docs/manifest.json +415 -0
- package/dist/docs/monetization/offerings.md +156 -0
- package/dist/docs/monetization/pricing-tables.md +226 -0
- package/dist/docs/monetization/targeting-rules.md +278 -0
- package/dist/docs/openapi.json +5479 -0
- package/dist/docs/payouts/overview.md +43 -0
- package/dist/docs/payouts/payout-account.md +12 -0
- package/dist/docs/payouts/transactions.md +23 -0
- package/dist/docs/product-catalog/digital-downloads.md +117 -0
- package/dist/docs/product-catalog/discounts.md +69 -0
- package/dist/docs/product-catalog/entitlements.md +428 -0
- package/dist/docs/product-catalog/free-and-trials.md +36 -0
- package/dist/docs/product-catalog/license-keys.md +324 -0
- package/dist/docs/product-catalog/links.md +92 -0
- package/dist/docs/product-catalog/location-based-pricing.md +41 -0
- package/dist/docs/product-catalog/one-time-payments.md +24 -0
- package/dist/docs/product-catalog/plans.md +199 -0
- package/dist/docs/product-catalog/products.md +60 -0
- package/dist/docs/product-catalog/subscriptions.md +29 -0
- package/dist/docs/product-catalog/tax-settings.md +37 -0
- package/dist/docs/product-catalog/usage-based-billing.md +119 -0
- package/dist/docs/promotions/create-a-promotion.md +75 -0
- package/dist/docs/promotions/customize-banner.md +41 -0
- package/dist/docs/promotions/integrate.md +38 -0
- package/dist/docs/promotions/overview.md +51 -0
- package/dist/docs/quickstart/core-concepts.md +146 -0
- package/dist/docs/quickstart/dashboard-setup.md +129 -0
- package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
- package/dist/docs/sales/checkout-sessions.md +58 -0
- package/dist/docs/sales/orders.md +76 -0
- package/dist/http/client.d.ts +28 -0
- package/dist/http/client.js +76 -0
- package/dist/http/client.js.map +1 -0
- package/dist/http/errors.d.ts +20 -0
- package/dist/http/errors.js +58 -0
- package/dist/http/errors.js.map +1 -0
- package/dist/resources/docs-index.d.ts +25 -0
- package/dist/resources/docs-index.js +109 -0
- package/dist/resources/docs-index.js.map +1 -0
- package/dist/resources/index.d.ts +2 -0
- package/dist/resources/index.js +73 -0
- package/dist/resources/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +1304 -0
- package/dist/schemas/kelviq.js +468 -0
- package/dist/schemas/kelviq.js.map +1 -0
- package/dist/server.d.ts +2 -0
- package/dist/server.js +41 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/_util.d.ts +15 -0
- package/dist/tools/_util.js +15 -0
- package/dist/tools/_util.js.map +1 -0
- package/dist/tools/checkout.d.ts +3 -0
- package/dist/tools/checkout.js +18 -0
- package/dist/tools/checkout.js.map +1 -0
- package/dist/tools/customers.d.ts +3 -0
- package/dist/tools/customers.js +32 -0
- package/dist/tools/customers.js.map +1 -0
- package/dist/tools/docs.d.ts +2 -0
- package/dist/tools/docs.js +43 -0
- package/dist/tools/docs.js.map +1 -0
- package/dist/tools/entitlements.d.ts +3 -0
- package/dist/tools/entitlements.js +22 -0
- package/dist/tools/entitlements.js.map +1 -0
- package/dist/tools/features.d.ts +3 -0
- package/dist/tools/features.js +55 -0
- package/dist/tools/features.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.js +44 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/licenses.d.ts +3 -0
- package/dist/tools/licenses.js +44 -0
- package/dist/tools/licenses.js.map +1 -0
- package/dist/tools/media.d.ts +3 -0
- package/dist/tools/media.js +18 -0
- package/dist/tools/media.js.map +1 -0
- package/dist/tools/offerings.d.ts +3 -0
- package/dist/tools/offerings.js +21 -0
- package/dist/tools/offerings.js.map +1 -0
- package/dist/tools/partner.d.ts +3 -0
- package/dist/tools/partner.js +55 -0
- package/dist/tools/partner.js.map +1 -0
- package/dist/tools/plan-entitlements.d.ts +3 -0
- package/dist/tools/plan-entitlements.js +56 -0
- package/dist/tools/plan-entitlements.js.map +1 -0
- package/dist/tools/plan-files.d.ts +3 -0
- package/dist/tools/plan-files.js +43 -0
- package/dist/tools/plan-files.js.map +1 -0
- package/dist/tools/plans.d.ts +3 -0
- package/dist/tools/plans.js +120 -0
- package/dist/tools/plans.js.map +1 -0
- package/dist/tools/portal.d.ts +3 -0
- package/dist/tools/portal.js +18 -0
- package/dist/tools/portal.js.map +1 -0
- package/dist/tools/product-files.d.ts +3 -0
- package/dist/tools/product-files.js +31 -0
- package/dist/tools/product-files.js.map +1 -0
- package/dist/tools/product-settings.d.ts +3 -0
- package/dist/tools/product-settings.js +31 -0
- package/dist/tools/product-settings.js.map +1 -0
- package/dist/tools/products.d.ts +3 -0
- package/dist/tools/products.js +69 -0
- package/dist/tools/products.js.map +1 -0
- package/dist/tools/promotions.d.ts +3 -0
- package/dist/tools/promotions.js +19 -0
- package/dist/tools/promotions.js.map +1 -0
- package/dist/tools/subscriptions.d.ts +3 -0
- package/dist/tools/subscriptions.js +63 -0
- package/dist/tools/subscriptions.js.map +1 -0
- package/dist/tools/usage.d.ts +3 -0
- package/dist/tools/usage.js +18 -0
- package/dist/tools/usage.js.map +1 -0
- package/package.json +88 -0
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Subscription Integration"
|
|
3
|
+
slug: "guides/subscription-integration"
|
|
4
|
+
section: "guides"
|
|
5
|
+
description: "A simple guide to add subscription billing to your SaaS in 5 API calls."
|
|
6
|
+
---
|
|
7
|
+
Add subscription billing to your SaaS with just a few API calls. This guide covers the REST API — for framework-specific guides, see [Next.js Integration](/guides/subscription-integration-for-nextjs).
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
Kelviq handles your subscription billing with these endpoints:
|
|
14
|
+
|
|
15
|
+
| Step | Endpoint | Purpose |
|
|
16
|
+
|------|----------|---------|
|
|
17
|
+
| 1 | Create Customer | Register user (optional) |
|
|
18
|
+
| 2 | Create Checkout | Start payment flow |
|
|
19
|
+
| 3 | Get Subscription | Check active plans |
|
|
20
|
+
| 4 | Update Subscription | Upgrade/downgrade |
|
|
21
|
+
| 5 | Check Entitlements | Gate features |
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Step 1: Create Customer (Optional)
|
|
26
|
+
|
|
27
|
+
You have two options for creating customers:
|
|
28
|
+
|
|
29
|
+
### Option 1: Auto-create during checkout
|
|
30
|
+
|
|
31
|
+
Skip this step. Pass `email` or `customerId` in the checkout request — Kelviq will auto-create the customer.
|
|
32
|
+
|
|
33
|
+
### Option 2: Create customer explicitly
|
|
34
|
+
|
|
35
|
+
Create a customer record when a user signs up.
|
|
36
|
+
|
|
37
|
+
```javascript
|
|
38
|
+
const response = await fetch("https://api.kelviq.com/api/v1/customers/", {
|
|
39
|
+
method: "POST",
|
|
40
|
+
headers: {
|
|
41
|
+
"Content-Type": "application/json",
|
|
42
|
+
"Authorization": "Bearer YOUR_SERVER_API_KEY"
|
|
43
|
+
},
|
|
44
|
+
body: JSON.stringify({
|
|
45
|
+
customerId: "user-123",
|
|
46
|
+
name: "John Doe",
|
|
47
|
+
email: "john@example.com"
|
|
48
|
+
})
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
const customer = await response.json();
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Pre-creating customers is useful when you want to track users in the dashboard before they subscribe.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Step 2: Create Checkout Session
|
|
59
|
+
|
|
60
|
+
When a user wants to subscribe, create a checkout session and redirect them.
|
|
61
|
+
|
|
62
|
+
### Request
|
|
63
|
+
|
|
64
|
+
```javascript
|
|
65
|
+
const response = await fetch("https://api.kelviq.com/api/v1/checkout/", {
|
|
66
|
+
method: "POST",
|
|
67
|
+
headers: {
|
|
68
|
+
"Content-Type": "application/json",
|
|
69
|
+
"Authorization": "Bearer YOUR_SERVER_API_KEY"
|
|
70
|
+
},
|
|
71
|
+
body: JSON.stringify({
|
|
72
|
+
planIdentifier: "pro",
|
|
73
|
+
chargePeriod: "MONTHLY",
|
|
74
|
+
customerId: "user-123",
|
|
75
|
+
successUrl: "https://yourapp.com/success"
|
|
76
|
+
})
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
const { checkoutUrl } = await response.json();
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Response
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"checkoutUrl": "https://www.kelviq.com/checkout/cs_fBhCIBerpe1pAsRW6P4wYc8WHqMdfdr457hd3oOLjhAFx/",
|
|
87
|
+
"checkoutSessionId": "cs_test_b1sNi7D6u9iMCUFV1UZi9ZwerfaiXKdOOmr3DCUW6XdCZIr5Id1F7G"
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Redirect user to `checkoutUrl` → They complete payment → Redirected back to your `successUrl`
|
|
92
|
+
|
|
93
|
+
### Required Parameters
|
|
94
|
+
|
|
95
|
+
| Parameter | Description |
|
|
96
|
+
|-----------|-------------|
|
|
97
|
+
| `planIdentifier` | The identifier of the plan (e.g., `"pro"`, `"enterprise"`) |
|
|
98
|
+
| `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
|
|
99
|
+
| `successUrl` | URL to redirect after successful payment |
|
|
100
|
+
|
|
101
|
+
### Optional Parameters
|
|
102
|
+
|
|
103
|
+
| Parameter | Description |
|
|
104
|
+
|-----------|-------------|
|
|
105
|
+
| `customerId` | Your customer ID (auto-creates if new) |
|
|
106
|
+
| `offeringId` | UUID of the offering |
|
|
107
|
+
| `pricingTableId` | UUID of the pricing table |
|
|
108
|
+
| `ipAddress` | Customer IP for location-based pricing |
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Step 3: Get Subscription Details
|
|
113
|
+
|
|
114
|
+
Check if a customer has an active subscription.
|
|
115
|
+
|
|
116
|
+
### Request
|
|
117
|
+
|
|
118
|
+
```javascript
|
|
119
|
+
const response = await fetch(
|
|
120
|
+
"https://api.kelviq.com/api/v1/subscriptions/?customer_id=user-123",
|
|
121
|
+
{
|
|
122
|
+
headers: {
|
|
123
|
+
"Authorization": "Bearer YOUR_SERVER_API_KEY"
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
);
|
|
127
|
+
|
|
128
|
+
const { results } = await response.json();
|
|
129
|
+
const activeSubscription = results.find(s => s.status === "active");
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Response
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"count": 1,
|
|
137
|
+
"next": null,
|
|
138
|
+
"previous": null,
|
|
139
|
+
"results": [
|
|
140
|
+
{
|
|
141
|
+
"id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
|
|
142
|
+
"status": "active",
|
|
143
|
+
"plan": {
|
|
144
|
+
"name": "Pro Plan",
|
|
145
|
+
"identifier": "pro"
|
|
146
|
+
},
|
|
147
|
+
"amount": "49.00",
|
|
148
|
+
"recurrence": "month",
|
|
149
|
+
"currency": "usd",
|
|
150
|
+
"startDate": "2024-01-01",
|
|
151
|
+
"endDate": null,
|
|
152
|
+
"customerId": "user-123"
|
|
153
|
+
}
|
|
154
|
+
]
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Step 4: Update Subscription
|
|
161
|
+
|
|
162
|
+
Allow users to upgrade or downgrade their plan.
|
|
163
|
+
|
|
164
|
+
### Request
|
|
165
|
+
|
|
166
|
+
```javascript
|
|
167
|
+
const response = await fetch(
|
|
168
|
+
"https://api.kelviq.com/api/v1/subscriptions/09d706ca-58f3-4fb2-818f-5b8623d67e6e/update/",
|
|
169
|
+
{
|
|
170
|
+
method: "POST",
|
|
171
|
+
headers: {
|
|
172
|
+
"Content-Type": "application/json",
|
|
173
|
+
"Authorization": "Bearer YOUR_SERVER_API_KEY"
|
|
174
|
+
},
|
|
175
|
+
body: JSON.stringify({
|
|
176
|
+
planIdentifier: "enterprise",
|
|
177
|
+
chargePeriod: "MONTHLY"
|
|
178
|
+
})
|
|
179
|
+
}
|
|
180
|
+
);
|
|
181
|
+
|
|
182
|
+
const data = await response.json();
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Response
|
|
186
|
+
|
|
187
|
+
```json
|
|
188
|
+
{
|
|
189
|
+
"subscriptionId": "09d706ca-58f3-4fb2-818f-5b8623d67e6e"
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Required Parameters
|
|
194
|
+
|
|
195
|
+
| Parameter | Description |
|
|
196
|
+
|-----------|-------------|
|
|
197
|
+
| `planIdentifier` | The identifier of the new plan |
|
|
198
|
+
| `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, etc. |
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## Step 5: Check Entitlements
|
|
203
|
+
|
|
204
|
+
Check what features a customer has access to based on their subscription.
|
|
205
|
+
|
|
206
|
+
### Request
|
|
207
|
+
|
|
208
|
+
```javascript
|
|
209
|
+
const response = await fetch(
|
|
210
|
+
"https://edge.api.kelviq.com/api/v1/entitlements/?customerId=user-123",
|
|
211
|
+
{
|
|
212
|
+
headers: {
|
|
213
|
+
"Authorization": "Bearer YOUR_CLIENT_API_KEY"
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
);
|
|
217
|
+
|
|
218
|
+
const { entitlements } = await response.json();
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Use your **Client API Key** for this endpoint, not your Server API Key.
|
|
222
|
+
|
|
223
|
+
### Response
|
|
224
|
+
|
|
225
|
+
```json
|
|
226
|
+
{
|
|
227
|
+
"customerId": "user-123",
|
|
228
|
+
"entitlements": [
|
|
229
|
+
{
|
|
230
|
+
"featureId": "export-data",
|
|
231
|
+
"featureType": "BOOLEAN",
|
|
232
|
+
"hasAccess": true
|
|
233
|
+
},
|
|
234
|
+
{
|
|
235
|
+
"featureId": "max-projects",
|
|
236
|
+
"featureType": "METER",
|
|
237
|
+
"hasAccess": true,
|
|
238
|
+
"usageLimit": 100,
|
|
239
|
+
"currentUsage": 45,
|
|
240
|
+
"remaining": 55
|
|
241
|
+
},
|
|
242
|
+
{
|
|
243
|
+
"featureId": "team-size",
|
|
244
|
+
"featureType": "CUSTOMIZABLE",
|
|
245
|
+
"hasAccess": true,
|
|
246
|
+
"usageLimit": 5
|
|
247
|
+
}
|
|
248
|
+
]
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### Entitlement Types
|
|
253
|
+
|
|
254
|
+
| Type | Description | Fields |
|
|
255
|
+
|------|-------------|--------|
|
|
256
|
+
| **BOOLEAN** | Feature on/off | `hasAccess` |
|
|
257
|
+
| **METER** | Usage-based limits | `usageLimit`, `currentUsage`, `remaining` |
|
|
258
|
+
| **CUSTOMIZABLE** | Configurable value | `usageLimit` |
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## Complete Flow
|
|
263
|
+
|
|
264
|
+
```
|
|
265
|
+
1. User signs up
|
|
266
|
+
→ Create customer via API (or auto-create via email)
|
|
267
|
+
|
|
268
|
+
2. User visits pricing page
|
|
269
|
+
→ Create checkout session
|
|
270
|
+
→ Redirect to checkout URL
|
|
271
|
+
→ User completes payment
|
|
272
|
+
→ Redirect back to your app
|
|
273
|
+
|
|
274
|
+
3. In your app
|
|
275
|
+
→ Get subscription details
|
|
276
|
+
→ Check entitlements
|
|
277
|
+
→ Show/hide features based on access
|
|
278
|
+
|
|
279
|
+
4. User wants to upgrade
|
|
280
|
+
→ Update subscription via API
|
|
281
|
+
→ Entitlements update automatically
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
## Need Help?
|
|
287
|
+
|
|
288
|
+
Have questions or need implementation support?
|
|
289
|
+
|
|
290
|
+
- Email us at **hi@kelviq.com**
|
|
291
|
+
- [Book a demo](https://tidycal.com/neravath/15-minute-meeting)
|