@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,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Overview"
|
|
3
|
+
slug: "payouts/overview"
|
|
4
|
+
section: "payouts"
|
|
5
|
+
description: "Connect your bank account and track cash flow"
|
|
6
|
+
---
|
|
7
|
+
We use Stripe to ensure you get paid fast and your tax documents are handled automatically.
|
|
8
|
+
|
|
9
|
+
## Setup
|
|
10
|
+
|
|
11
|
+
Before you can receive funds, you need to connect a bank account.
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
Navigate to the **Payouts** group and click the **Set up payout** button.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
You will be redirected to a secure Stripe form. Choose your account type (Individual or Company) and enter your banking details.
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
<img height="200" src="/images/payout-setup-cta.png" alt="Payout setup screen with CTA" />
|
|
24
|
+
|
|
25
|
+
## Dashboard
|
|
26
|
+
|
|
27
|
+
Once set up, the main Payouts view gives you a real-time snapshot of your cash flow.
|
|
28
|
+
|
|
29
|
+
<img height="200" src="/images/payout-dashboard.png" alt="Payout dashboard showing available funds and processing amounts" />
|
|
30
|
+
|
|
31
|
+
### Key metrics
|
|
32
|
+
* **Available to payout**
|
|
33
|
+
The funds that have cleared and are ready to be transferred to your bank.
|
|
34
|
+
* **Processing amount**
|
|
35
|
+
Revenue that is currently being processed. You can see the estimated date for when these funds will become available.
|
|
36
|
+
* **Billing cycle**
|
|
37
|
+
Shows your current schedule. If funds are available, you can click **Withdraw funds** to initiate a manual transfer immediately.
|
|
38
|
+
|
|
39
|
+
### Payout history
|
|
40
|
+
Below the metrics, you will see a list of every payout we have sent to your bank.
|
|
41
|
+
* Check the status of past transfers.
|
|
42
|
+
* See the exact date the funds landed.
|
|
43
|
+
* View the destination bank account for each transfer.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Payout Settings"
|
|
3
|
+
slug: "payouts/payout-account"
|
|
4
|
+
section: "payouts"
|
|
5
|
+
description: "Manage bank accounts and transfer schedules"
|
|
6
|
+
---
|
|
7
|
+
The **Payout Account** tab lets you control how and when you get paid.
|
|
8
|
+
|
|
9
|
+
<img height="200" src="/images/payout-settings.png" alt="Payout settings showing bank account and schedule preferences" />
|
|
10
|
+
|
|
11
|
+
## Bank account
|
|
12
|
+
View the currently connected bank account. You can also click the link to view your full verification status directly on Stripe.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Transactions"
|
|
3
|
+
slug: "payouts/transactions"
|
|
4
|
+
section: "payouts"
|
|
5
|
+
description: "Audit individual payments, fees, and net earnings"
|
|
6
|
+
---
|
|
7
|
+
The **Transactions** tab provides a granular breakdown of every single movement of money. This includes successful payments, refunds, and failures.
|
|
8
|
+
|
|
9
|
+
<img height="200" src="/images/payout-transactions-list.png" alt="List of individual transactions with status filters" />
|
|
10
|
+
|
|
11
|
+
## Filtering
|
|
12
|
+
You can filter the list to find specific issues.
|
|
13
|
+
* **Success:** Completed payments.
|
|
14
|
+
* **Refunded:** Money returned to customers.
|
|
15
|
+
* **Failed:** Declined cards or failed transfers.
|
|
16
|
+
|
|
17
|
+
## Transaction details
|
|
18
|
+
Click on any transaction row to open the details view. This breaks down the math so you know exactly what you earned from that specific order.
|
|
19
|
+
|
|
20
|
+
* **Gross total:** The amount the customer paid.
|
|
21
|
+
* **Processing fees:** The platform and gateway fees deducted.
|
|
22
|
+
* **Net earnings:** The final amount added to your balance.
|
|
23
|
+
* **Payment details:** The card or method used.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Digital Downloads"
|
|
3
|
+
slug: "product-catalog/digital-downloads"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Enable customers to download digital files after purchase"
|
|
6
|
+
---
|
|
7
|
+
Digital Downloads allow you to attach downloadable files to your plans. Customers who purchase your plan can access these files after completing their purchase.
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
Use Digital Downloads to deliver:
|
|
12
|
+
- **Course content** – PDFs, videos, or supplementary materials
|
|
13
|
+
- **E-books** – Digital books in PDF, EPUB, or other formats
|
|
14
|
+
- **Software** – Installers, license files, or application packages
|
|
15
|
+
- **Templates** – Design files, spreadsheets, or document templates
|
|
16
|
+
- **Any other digital content** your customers need
|
|
17
|
+
|
|
18
|
+
## Accessing Digital Downloads
|
|
19
|
+
|
|
20
|
+
<img height="200" src="/images/accessing-digital-downloads.png" />
|
|
21
|
+
|
|
22
|
+
1. Navigate to **Products** in the sidebar
|
|
23
|
+
2. Select the product containing your plan
|
|
24
|
+
3. Click on the plan you want to edit
|
|
25
|
+
4. Scroll down to the **Digital downloads** section
|
|
26
|
+
5. Click the expand arrow to open the section
|
|
27
|
+
|
|
28
|
+
## Uploading Files
|
|
29
|
+
|
|
30
|
+
### How to Upload
|
|
31
|
+
|
|
32
|
+
<img height="200" src="/images/uploading-files.png" />
|
|
33
|
+
|
|
34
|
+
1. Open the **Digital downloads** section
|
|
35
|
+
2. Click anywhere in the upload area, or drag and drop files directly
|
|
36
|
+
3. Select one or more files from your computer
|
|
37
|
+
4. Files will begin uploading automatically
|
|
38
|
+
5. Once complete, files appear in the **Uploads** list
|
|
39
|
+
|
|
40
|
+
### Upload Progress
|
|
41
|
+
|
|
42
|
+
<img height="200" src="/images/upload-progress.png" />
|
|
43
|
+
|
|
44
|
+
While uploading, you'll see:
|
|
45
|
+
- File name and size
|
|
46
|
+
- Progress bar showing upload percentage
|
|
47
|
+
- Status indicator (uploading, complete, or error)
|
|
48
|
+
|
|
49
|
+
### File Size Limits
|
|
50
|
+
|
|
51
|
+
- **Maximum file size**: 5 GB per file
|
|
52
|
+
- **Multiple files**: You can upload multiple files at once
|
|
53
|
+
|
|
54
|
+
### Supported File Types
|
|
55
|
+
|
|
56
|
+
All file types are supported, including:
|
|
57
|
+
- Documents: PDF, DOCX, TXT, etc.
|
|
58
|
+
- Images: PNG, JPG, GIF, SVG, etc.
|
|
59
|
+
- Videos: MP4, MOV, AVI, etc.
|
|
60
|
+
- Audio: MP3, WAV, FLAC, etc.
|
|
61
|
+
- Archives: ZIP, RAR, 7Z, etc.
|
|
62
|
+
- Software: EXE, DMG, APP, etc.
|
|
63
|
+
- Any other file format
|
|
64
|
+
|
|
65
|
+
## Managing Files
|
|
66
|
+
Each uploaded file has a toggle switch and a menu button (**⋯**) with additional options.
|
|
67
|
+
|
|
68
|
+
### Enable/Disable Files
|
|
69
|
+
|
|
70
|
+
You can temporarily hide files from customers without deleting them:
|
|
71
|
+
|
|
72
|
+
<img height="200" src="/images/enable-disable-files.png" />
|
|
73
|
+
|
|
74
|
+
1. Find the file in the uploads list
|
|
75
|
+
2. Click the toggle switch next to the file
|
|
76
|
+
3. **Enabled** (toggle on): Customers can download this file
|
|
77
|
+
4. **Disabled** (toggle off): File is hidden from customers
|
|
78
|
+
|
|
79
|
+
This is useful when you need to temporarily remove access to a file or prepare files before making them available.
|
|
80
|
+
|
|
81
|
+
### File Actions Menu
|
|
82
|
+
|
|
83
|
+
Click the menu button (**⋯**) next to any file to access additional options:
|
|
84
|
+
|
|
85
|
+
<img height="200" src="/images/managing-files.png" />
|
|
86
|
+
|
|
87
|
+
#### Download
|
|
88
|
+
|
|
89
|
+
Use the **Download** option to:
|
|
90
|
+
- Verify that the file uploaded correctly
|
|
91
|
+
- Check file contents before enabling for customers
|
|
92
|
+
- Save a local backup of uploaded files
|
|
93
|
+
|
|
94
|
+
To download a file:
|
|
95
|
+
1. Click the **⋯** menu button next to the file
|
|
96
|
+
2. Select **Download**
|
|
97
|
+
3. The file will download to your computer
|
|
98
|
+
|
|
99
|
+
#### Delete
|
|
100
|
+
|
|
101
|
+
To permanently remove a file:
|
|
102
|
+
|
|
103
|
+
1. Click the **⋯** menu button next to the file
|
|
104
|
+
2. Select **Delete**
|
|
105
|
+
3. The file will be permanently removed
|
|
106
|
+
|
|
107
|
+
> **Note**: Deleted files cannot be recovered. Make sure you have a backup before deleting.
|
|
108
|
+
|
|
109
|
+
## Customer Experience
|
|
110
|
+
|
|
111
|
+
After a successful purchase, customers can:
|
|
112
|
+
|
|
113
|
+
1. Access the order confirmation page
|
|
114
|
+
2. View all downloadable files associated with their purchased plan
|
|
115
|
+
3. Click to download each file directly
|
|
116
|
+
|
|
117
|
+
Files remain accessible to customers as long as their subscription or purchase is active.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Discounts"
|
|
3
|
+
slug: "product-catalog/discounts"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Create coupons and promotional codes"
|
|
6
|
+
---
|
|
7
|
+
You can manage all your coupons from the **Product Catalog**.
|
|
8
|
+
|
|
9
|
+
Navigate to **Product Catalog > Discounts** to see a list of every active and expired code. You can create two types of discounts:
|
|
10
|
+
* **Percentage:** A relative cut (e.g. 20% off).
|
|
11
|
+
* **Fixed amount:** A specific dollar value (e.g. $10 off).
|
|
12
|
+
|
|
13
|
+
## Create a discount
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
Click **+ Create discount** in the top right corner.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
Choose the discount type (Percentage or Fixed amount) and enter the value.
|
|
23
|
+
* **Name:** The internal name for your reference.
|
|
24
|
+
* **Discount code:** The text the customer enters at checkout. You can type your own or click the **refresh icon** to auto-generate a secure random code.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
Set the duration, limits, and product scope (detailed below).
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
Click **Create discount** to make the code live immediately.
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
<img height="200" src="/images/create-discount-modal.png" alt="Discount creation modal showing percentage and code options" />
|
|
38
|
+
|
|
39
|
+
## Configuration options
|
|
40
|
+
|
|
41
|
+
You can control exactly how and when a discount applies.
|
|
42
|
+
|
|
43
|
+
### Duration
|
|
44
|
+
For recurring subscriptions, you define how long the discount lasts.
|
|
45
|
+
* **Once:** Applies only to the first invoice.
|
|
46
|
+
* **Forever:** Applies to every invoice indefinitely.
|
|
47
|
+
* **Repeating:** Applies for a specific number of billing cycles (e.g. "3 months off").
|
|
48
|
+
|
|
49
|
+
### Usage & expiry
|
|
50
|
+
Control the scarcity of the coupon.
|
|
51
|
+
* **Redemption limit:** Set a total number of times this code can be used (e.g. "First 100 users").
|
|
52
|
+
* **Expiry date:** Set a hard deadline when the code stops working.
|
|
53
|
+
|
|
54
|
+
### Product restrictions
|
|
55
|
+
By default, a discount applies to your entire catalog. You can restrict it to specific items.
|
|
56
|
+
|
|
57
|
+
1. Toggle **Limit discount on selected products**.
|
|
58
|
+
2. Select the products you want to include.
|
|
59
|
+
3. **Refine scope:** You can go even deeper by selecting specific price points.
|
|
60
|
+
* *Example:* Apply the discount only to the "Pro Plan - Yearly" interval, while excluding the "Monthly" version.
|
|
61
|
+
|
|
62
|
+
## Management
|
|
63
|
+
|
|
64
|
+
The main discounts tab shows the status of every code you have created.
|
|
65
|
+
|
|
66
|
+
<img height="200" src="/images/discounts-list.png" alt="List of active and expired discounts" />
|
|
67
|
+
|
|
68
|
+
* **Active:** The code is live and redeemable.
|
|
69
|
+
* **Expired:** The code has passed its end date or hit its usage limit.
|
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Features & Limits (Entitlements)"
|
|
3
|
+
slug: "product-catalog/entitlements"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Control feature access for your customers"
|
|
6
|
+
---
|
|
7
|
+
Entitlements are the modern way to control feature access in your application. Instead of checking which plan a customer is on, you check which features they have access to. This fundamental shift gives you unprecedented flexibility to experiment with pricing, create custom deals, and iterate on your product—all without changing code.
|
|
8
|
+
|
|
9
|
+
<img height="200" src="/images/features-limits-enttilements.png" />
|
|
10
|
+
|
|
11
|
+
For SDK installation and API reference, see:
|
|
12
|
+
- [Node SDK Documentation](https://docs.kelviq.com/backend-integration/node-sdk)
|
|
13
|
+
- [Entitlements API Reference](https://docs.kelviq.com/api-reference/entitlements/retrieve-customer-entitlements)
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Why Entitlements?
|
|
18
|
+
|
|
19
|
+
### The Problem with Plan-Based Access
|
|
20
|
+
|
|
21
|
+
Traditional SaaS applications check access like this:
|
|
22
|
+
|
|
23
|
+
```javascript
|
|
24
|
+
// ❌ The old way - hardcoded, brittle, requires code changes
|
|
25
|
+
if (user.plan === 'pro' || user.plan === 'enterprise') {
|
|
26
|
+
showAdvancedAnalytics();
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
if (user.plan === 'enterprise') {
|
|
30
|
+
enableSSO();
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
This approach has serious limitations:
|
|
35
|
+
|
|
36
|
+
- **Code changes required** for any pricing restructure
|
|
37
|
+
- **Deployment needed** to move a feature between plans
|
|
38
|
+
- **Engineering bottleneck** for every pricing experiment
|
|
39
|
+
- **Webhook complexity** to sync subscription state
|
|
40
|
+
- **Stale cache issues** when plans change
|
|
41
|
+
- **Custom deals are painful** requiring one-off code
|
|
42
|
+
|
|
43
|
+
### The Entitlements Approach
|
|
44
|
+
|
|
45
|
+
With Kelviq, you check features directly:
|
|
46
|
+
|
|
47
|
+
```javascript
|
|
48
|
+
// ✅ The Kelviq way - flexible, decoupled, no code changes needed
|
|
49
|
+
const hasAnalytics = await client.entitlements.hasAccess({
|
|
50
|
+
customerId: "cust_123",
|
|
51
|
+
featureId: "advanced-analytics"
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
if (hasAnalytics) {
|
|
55
|
+
showAdvancedAnalytics();
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Now you can:
|
|
60
|
+
- Move features between plans without code changes
|
|
61
|
+
- Create custom enterprise deals in minutes
|
|
62
|
+
- A/B test pricing without deployments
|
|
63
|
+
- Let Sales and Product iterate independently
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## How It Works
|
|
68
|
+
|
|
69
|
+
### The Flow
|
|
70
|
+
|
|
71
|
+
<img height="200" src="/images/features-kelviq-dashboard.png" />
|
|
72
|
+
|
|
73
|
+
1) Setup plans and features on Kelviq Dashboard
|
|
74
|
+
1) When a customer completes checkout, their entitlements are automatically assigned.
|
|
75
|
+
1) Your app checks access via SDK
|
|
76
|
+
1) Customer gets immediate access
|
|
77
|
+
|
|
78
|
+
### No Webhooks Required
|
|
79
|
+
|
|
80
|
+
When a customer completes checkout:
|
|
81
|
+
|
|
82
|
+
1. Payment is processed
|
|
83
|
+
2. Entitlements are assigned **automatically**
|
|
84
|
+
3. Your app checks access via SDK
|
|
85
|
+
4. Customer gets immediate access
|
|
86
|
+
|
|
87
|
+
You don't need to:
|
|
88
|
+
- Build webhook handlers
|
|
89
|
+
- Sync subscription state to your database
|
|
90
|
+
- Handle race conditions
|
|
91
|
+
- Manage cache invalidation
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Feature Types
|
|
96
|
+
|
|
97
|
+
Kelviq supports three types of features to cover all access control scenarios.
|
|
98
|
+
|
|
99
|
+
### Boolean Features
|
|
100
|
+
|
|
101
|
+
Simple on/off access control.
|
|
102
|
+
|
|
103
|
+
<img height="200" src="/images/boolean.png" />
|
|
104
|
+
|
|
105
|
+
**Use for:**
|
|
106
|
+
- Feature flags (SSO, API access, white-labeling)
|
|
107
|
+
- Premium features (advanced analytics, custom branding)
|
|
108
|
+
- Access gates (admin panel, beta features)
|
|
109
|
+
|
|
110
|
+
**Example configuration:**
|
|
111
|
+
|
|
112
|
+
| Feature | Starter | Pro | Enterprise |
|
|
113
|
+
|---------|---------|-----|------------|
|
|
114
|
+
| Basic Dashboard | ✓ | ✓ | ✓ |
|
|
115
|
+
| Advanced Analytics | ✗ | ✓ | ✓ |
|
|
116
|
+
| SSO | ✗ | ✗ | ✓ |
|
|
117
|
+
| White Label | ✗ | ✗ | ✓ |
|
|
118
|
+
|
|
119
|
+
### Meter Features
|
|
120
|
+
|
|
121
|
+
Usage-based features with limits and tracking.
|
|
122
|
+
|
|
123
|
+
<img height="200" src="/images/raw-meter(empty-state).png" />
|
|
124
|
+
|
|
125
|
+
**Use for:**
|
|
126
|
+
- API calls, requests, or operations
|
|
127
|
+
- Storage (GB, files, records)
|
|
128
|
+
- Team members or seats
|
|
129
|
+
- Messages, emails, or notifications
|
|
130
|
+
- AI tokens or credits
|
|
131
|
+
|
|
132
|
+
**Configuration options:**
|
|
133
|
+
|
|
134
|
+
| Option | Description |
|
|
135
|
+
|--------|-------------|
|
|
136
|
+
| **Limit** | Maximum usage allowed (or unlimited) |
|
|
137
|
+
| **Reset Period** | When usage resets (monthly, weekly, daily, never) |
|
|
138
|
+
| **Hard Limit** | Block access when limit reached |
|
|
139
|
+
| **Soft Limit** | Allow overages but notify/warn |
|
|
140
|
+
| **Rollover** | Carry unused quota to next period |
|
|
141
|
+
|
|
142
|
+
<img height="200" src="/images/aggregate-meter.png" />
|
|
143
|
+
|
|
144
|
+
**Example configuration:**
|
|
145
|
+
|
|
146
|
+
| Feature | Starter | Pro | Enterprise |
|
|
147
|
+
|---------|---------|-----|------------|
|
|
148
|
+
| API Calls | 1,000/mo | 100,000/mo | Unlimited |
|
|
149
|
+
| Storage | 5 GB | 100 GB | 1 TB |
|
|
150
|
+
| Team Members | 3 | 25 | Unlimited |
|
|
151
|
+
|
|
152
|
+
### Customizable Features
|
|
153
|
+
|
|
154
|
+
Dynamic values that aren't simple on/off or numeric limits.
|
|
155
|
+
|
|
156
|
+
<img height="200" src="/images/customizable.png" />
|
|
157
|
+
|
|
158
|
+
**Use for:**
|
|
159
|
+
- Configuration values
|
|
160
|
+
- Tier-specific settings
|
|
161
|
+
- Dynamic feature behavior
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Soft Limits vs. Hard Limits
|
|
166
|
+
|
|
167
|
+
Choose the right enforcement strategy for each feature.
|
|
168
|
+
|
|
169
|
+
<img height="200" src="/images/hard-limit.png" />
|
|
170
|
+
|
|
171
|
+
### Hard Limits
|
|
172
|
+
|
|
173
|
+
Block access completely when the limit is reached.
|
|
174
|
+
|
|
175
|
+
**Best for:**
|
|
176
|
+
- Cost-sensitive features (AI tokens, bandwidth)
|
|
177
|
+
- Preventing abuse
|
|
178
|
+
- Strict contractual limits
|
|
179
|
+
|
|
180
|
+
### Soft Limits
|
|
181
|
+
|
|
182
|
+
Allow continued access but notify the user.
|
|
183
|
+
|
|
184
|
+
**Best for:**
|
|
185
|
+
- Driving upgrades without blocking users
|
|
186
|
+
- Features where occasional overages are acceptable
|
|
187
|
+
- Better user experience during high-usage periods
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Checkout Integration
|
|
192
|
+
|
|
193
|
+
When a customer goes through checkout, entitlements are automatically assigned. The key is passing the customer ID.
|
|
194
|
+
|
|
195
|
+
### Passing Customer ID
|
|
196
|
+
|
|
197
|
+
When creating a checkout session, include the customer identifier:
|
|
198
|
+
|
|
199
|
+
```javascript
|
|
200
|
+
import { Kelviq, CHARGE_PERIOD_CHOICES } from '@kelviq/node-sdk';
|
|
201
|
+
|
|
202
|
+
const response = await client.checkout.createSession({
|
|
203
|
+
planIdentifier: "plan-pro-monthly",
|
|
204
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
205
|
+
successUrl: "https://yourapp.com/checkout/success",
|
|
206
|
+
customerId: "cust_789", // Your customer ID - recommended
|
|
207
|
+
});
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Always pass a `customerId` when creating checkout sessions. If you don't, a new customer will be created automatically, which may lead to duplicate customer records.
|
|
211
|
+
|
|
212
|
+
For complete checkout API options, see the [Node SDK Documentation](https://docs.kelviq.com/backend-integration/node-sdk).
|
|
213
|
+
|
|
214
|
+
### New vs. Existing Customers
|
|
215
|
+
|
|
216
|
+
| Scenario | What Happens |
|
|
217
|
+
|----------|--------------|
|
|
218
|
+
| **New customer ID** | Customer created automatically, entitlements assigned |
|
|
219
|
+
| **Existing customer** | Entitlements updated based on new purchase |
|
|
220
|
+
| **Upgrade** | New plan entitlements replace old ones |
|
|
221
|
+
| **Downgrade** | Adjusted at end of current billing period |
|
|
222
|
+
|
|
223
|
+
### Automatic Assignment
|
|
224
|
+
|
|
225
|
+
After successful payment:
|
|
226
|
+
|
|
227
|
+
1. Customer record is created/updated
|
|
228
|
+
2. Plan entitlements are assigned instantly
|
|
229
|
+
3. No webhook processing needed
|
|
230
|
+
4. Customer can access features immediately
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## SDK Integration
|
|
235
|
+
|
|
236
|
+
### Quick Start
|
|
237
|
+
|
|
238
|
+
Install the SDK and start checking entitlements in minutes.
|
|
239
|
+
|
|
240
|
+
```bash npm
|
|
241
|
+
npm install @kelviq/node-sdk
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
```bash yarn
|
|
245
|
+
yarn add @kelviq/node-sdk
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
```javascript
|
|
249
|
+
import { Kelviq } from '@kelviq/node-sdk';
|
|
250
|
+
|
|
251
|
+
const client = new Kelviq({
|
|
252
|
+
accessToken: process.env.KELVIQ_ACCESS_TOKEN
|
|
253
|
+
});
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Get your API key from **Settings → [API keys](https://app.kelviq.com/settings/api-keys)** in the Kelviq dashboard.
|
|
257
|
+
|
|
258
|
+
### Checking Feature Access
|
|
259
|
+
|
|
260
|
+
```javascript
|
|
261
|
+
// Check boolean feature access
|
|
262
|
+
const hasAccess = await client.entitlements.hasAccess({
|
|
263
|
+
customerId: "cust_123",
|
|
264
|
+
featureId: "advanced-analytics"
|
|
265
|
+
});
|
|
266
|
+
|
|
267
|
+
if (hasAccess) {
|
|
268
|
+
showAdvancedAnalytics();
|
|
269
|
+
} else {
|
|
270
|
+
showUpgradePrompt();
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### Reporting Usage
|
|
275
|
+
|
|
276
|
+
For meter features, report usage after each consumption:
|
|
277
|
+
|
|
278
|
+
```javascript
|
|
279
|
+
import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';
|
|
280
|
+
|
|
281
|
+
// Increment usage by a value (DELTA)
|
|
282
|
+
await client.reporting.reportUsage({
|
|
283
|
+
value: 1,
|
|
284
|
+
customerId: "cust_123",
|
|
285
|
+
featureId: "api-calls",
|
|
286
|
+
behaviour: BEHAVIOUR_CHOICES.DELTA // Adds to current usage
|
|
287
|
+
});
|
|
288
|
+
|
|
289
|
+
// Or set absolute value (SET)
|
|
290
|
+
await client.reporting.reportUsage({
|
|
291
|
+
value: 150,
|
|
292
|
+
customerId: "cust_123",
|
|
293
|
+
featureId: "seats",
|
|
294
|
+
behaviour: BEHAVIOUR_CHOICES.SET // Replaces current usage
|
|
295
|
+
});
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
For complete SDK reference including all methods and parameters, see the [Node SDK Documentation](https://docs.kelviq.com/backend-integration/node-sdk).
|
|
299
|
+
|
|
300
|
+
The sandbox environment is completely separate from production. Use different API keys and note that sandbox data won't appear in production.
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## Managing Customer Entitlements
|
|
305
|
+
|
|
306
|
+
### Viewing Customer Entitlements
|
|
307
|
+
|
|
308
|
+
In the Kelviq dashboard:
|
|
309
|
+
|
|
310
|
+
1. Navigate to **Customers**
|
|
311
|
+
2. Select a customer
|
|
312
|
+
3. View their **Features** section
|
|
313
|
+
|
|
314
|
+
You'll see:
|
|
315
|
+
- All entitled features
|
|
316
|
+
- Current usage vs. limits
|
|
317
|
+
- Reset dates for meters
|
|
318
|
+
- Whether values are overridden
|
|
319
|
+
|
|
320
|
+
### Overriding Entitlements
|
|
321
|
+
|
|
322
|
+
Sometimes you need to give a specific customer different access than their plan provides.
|
|
323
|
+
|
|
324
|
+
**Common scenarios:**
|
|
325
|
+
- Sales gave a prospect extra API calls for a POC
|
|
326
|
+
- Customer needs temporary limit increase
|
|
327
|
+
- VIP customer gets special access
|
|
328
|
+
- Compensating for a service issue
|
|
329
|
+
|
|
330
|
+
**To override:**
|
|
331
|
+
|
|
332
|
+
1. Go to the customer's detail page
|
|
333
|
+
2. Find the feature in the Features section
|
|
334
|
+
3. Click the menu (⋯) → **Override usage**
|
|
335
|
+
4. Set the new value
|
|
336
|
+
5. Save
|
|
337
|
+
|
|
338
|
+
Overrides are:
|
|
339
|
+
- Per-customer (don't affect the plan)
|
|
340
|
+
- Marked with an override indicator
|
|
341
|
+
- Can be reverted anytime
|
|
342
|
+
|
|
343
|
+
### Resetting Usage
|
|
344
|
+
|
|
345
|
+
For meter features, you can reset a customer's usage:
|
|
346
|
+
|
|
347
|
+
1. Go to the customer's detail page
|
|
348
|
+
2. Find the meter feature
|
|
349
|
+
3. Click the menu (⋯) → **Reset usage**
|
|
350
|
+
|
|
351
|
+
This sets their current usage back to 0, giving them their full quota again.
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
## Plan Inheritance
|
|
356
|
+
|
|
357
|
+
Create plan hierarchies to reduce duplication and maintain consistency.
|
|
358
|
+
|
|
359
|
+
### How It Works
|
|
360
|
+
|
|
361
|
+
```
|
|
362
|
+
Enterprise Plan
|
|
363
|
+
└── inherits from → Pro Plan
|
|
364
|
+
└── inherits from → Starter Plan
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
When you set up inheritance:
|
|
368
|
+
- Child plan automatically gets parent's features
|
|
369
|
+
- You can override specific values in the child
|
|
370
|
+
- Changes to parent propagate to children (unless overridden)
|
|
371
|
+
|
|
372
|
+
### Override Indicators
|
|
373
|
+
|
|
374
|
+
| Icon | Meaning |
|
|
375
|
+
|------|---------|
|
|
376
|
+
| 🔗 Inherited | Value comes from parent plan, stays in sync |
|
|
377
|
+
| ⚡ Overridden | Value was customized, no longer syncs with parent |
|
|
378
|
+
|
|
379
|
+
### Use Cases
|
|
380
|
+
|
|
381
|
+
**Tiered plans:**
|
|
382
|
+
- Starter: 1,000 API calls
|
|
383
|
+
- Pro: inherits Starter + overrides API calls to 100,000 + adds analytics
|
|
384
|
+
- Enterprise: inherits Pro + overrides to unlimited + adds SSO
|
|
385
|
+
|
|
386
|
+
**Regional plans:**
|
|
387
|
+
- US Pro: standard features
|
|
388
|
+
- EU Pro: inherits US Pro + adds GDPR compliance features
|
|
389
|
+
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
## Subscription Lifecycle
|
|
393
|
+
|
|
394
|
+
### What Happens During...
|
|
395
|
+
|
|
396
|
+
#### Successful Purchase
|
|
397
|
+
- Entitlements assigned immediately
|
|
398
|
+
- Customer can access features right away
|
|
399
|
+
- No webhook handling required
|
|
400
|
+
|
|
401
|
+
#### Upgrade
|
|
402
|
+
- New plan entitlements replace old ones
|
|
403
|
+
- Happens immediately
|
|
404
|
+
- Usage meters may reset or carry over (configurable)
|
|
405
|
+
|
|
406
|
+
#### Downgrade
|
|
407
|
+
- New entitlements take effect at end of billing period
|
|
408
|
+
- Customer keeps current access until then
|
|
409
|
+
- Prevents mid-cycle disruption
|
|
410
|
+
|
|
411
|
+
#### Cancellation
|
|
412
|
+
- Entitlements remain active until period ends
|
|
413
|
+
- Customer can use features they paid for
|
|
414
|
+
- Access revoked when subscription expires
|
|
415
|
+
|
|
416
|
+
#### Failed Payment
|
|
417
|
+
- Grace period begins (configurable)
|
|
418
|
+
- Customer retains access during grace period
|
|
419
|
+
- After grace period: access revoked
|
|
420
|
+
- Entitlements restored when payment succeeds
|
|
421
|
+
|
|
422
|
+
#### Refund
|
|
423
|
+
- Entitlements revoked immediately
|
|
424
|
+
- Customer loses access to plan features
|
|
425
|
+
|
|
426
|
+
Manage subscriptions programmatically using the [Subscriptions API](https://docs.kelviq.com/backend-integration/node-sdk#subscriptions).
|
|
427
|
+
|
|
428
|
+
---
|