@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.
Files changed (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +322 -0
  3. package/dist/config.d.ts +16 -0
  4. package/dist/config.js +45 -0
  5. package/dist/config.js.map +1 -0
  6. package/dist/docs/README.md +128 -0
  7. package/dist/docs/api-reference/authentication.md +41 -0
  8. package/dist/docs/backend-integration/node-sdk.md +1040 -0
  9. package/dist/docs/backend-integration/python-sdk.md +1198 -0
  10. package/dist/docs/changelog/app.md +80 -0
  11. package/dist/docs/changelog/checkout-api.md +59 -0
  12. package/dist/docs/changelog/js-promotions-ui.md +14 -0
  13. package/dist/docs/changelog/js-sdk.md +281 -0
  14. package/dist/docs/changelog/node-sdk.md +378 -0
  15. package/dist/docs/changelog/python-sdk.md +456 -0
  16. package/dist/docs/changelog/react-sdk.md +580 -0
  17. package/dist/docs/checkout/checkout-configuration.md +434 -0
  18. package/dist/docs/coustomers-management/overview.md +111 -0
  19. package/dist/docs/customer-portal/overview.md +81 -0
  20. package/dist/docs/frontend-integration/js-sdk.md +676 -0
  21. package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
  22. package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
  23. package/dist/docs/frontend-integration/react-sdk.md +1187 -0
  24. package/dist/docs/frontend-integration/react-ui.md +771 -0
  25. package/dist/docs/getstarted/fees.md +160 -0
  26. package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
  27. package/dist/docs/getstarted/merchant-of-record.md +64 -0
  28. package/dist/docs/getstarted/review-process.md +190 -0
  29. package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
  30. package/dist/docs/guides/subscription-integration.md +291 -0
  31. package/dist/docs/guides/webhooks.md +963 -0
  32. package/dist/docs/legal/approved-prohibited-policy.md +252 -0
  33. package/dist/docs/legal/buyer-terms.md +177 -0
  34. package/dist/docs/legal/compliant-user-flow.md +216 -0
  35. package/dist/docs/legal/master-service-agreement.md +404 -0
  36. package/dist/docs/legal/payment-flow-diagram.md +188 -0
  37. package/dist/docs/legal/seller-terms.md +169 -0
  38. package/dist/docs/manifest.json +415 -0
  39. package/dist/docs/monetization/offerings.md +156 -0
  40. package/dist/docs/monetization/pricing-tables.md +226 -0
  41. package/dist/docs/monetization/targeting-rules.md +278 -0
  42. package/dist/docs/openapi.json +5479 -0
  43. package/dist/docs/payouts/overview.md +43 -0
  44. package/dist/docs/payouts/payout-account.md +12 -0
  45. package/dist/docs/payouts/transactions.md +23 -0
  46. package/dist/docs/product-catalog/digital-downloads.md +117 -0
  47. package/dist/docs/product-catalog/discounts.md +69 -0
  48. package/dist/docs/product-catalog/entitlements.md +428 -0
  49. package/dist/docs/product-catalog/free-and-trials.md +36 -0
  50. package/dist/docs/product-catalog/license-keys.md +324 -0
  51. package/dist/docs/product-catalog/links.md +92 -0
  52. package/dist/docs/product-catalog/location-based-pricing.md +41 -0
  53. package/dist/docs/product-catalog/one-time-payments.md +24 -0
  54. package/dist/docs/product-catalog/plans.md +199 -0
  55. package/dist/docs/product-catalog/products.md +60 -0
  56. package/dist/docs/product-catalog/subscriptions.md +29 -0
  57. package/dist/docs/product-catalog/tax-settings.md +37 -0
  58. package/dist/docs/product-catalog/usage-based-billing.md +119 -0
  59. package/dist/docs/promotions/create-a-promotion.md +75 -0
  60. package/dist/docs/promotions/customize-banner.md +41 -0
  61. package/dist/docs/promotions/integrate.md +38 -0
  62. package/dist/docs/promotions/overview.md +51 -0
  63. package/dist/docs/quickstart/core-concepts.md +146 -0
  64. package/dist/docs/quickstart/dashboard-setup.md +129 -0
  65. package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
  66. package/dist/docs/sales/checkout-sessions.md +58 -0
  67. package/dist/docs/sales/orders.md +76 -0
  68. package/dist/http/client.d.ts +28 -0
  69. package/dist/http/client.js +76 -0
  70. package/dist/http/client.js.map +1 -0
  71. package/dist/http/errors.d.ts +20 -0
  72. package/dist/http/errors.js +58 -0
  73. package/dist/http/errors.js.map +1 -0
  74. package/dist/resources/docs-index.d.ts +25 -0
  75. package/dist/resources/docs-index.js +109 -0
  76. package/dist/resources/docs-index.js.map +1 -0
  77. package/dist/resources/index.d.ts +2 -0
  78. package/dist/resources/index.js +73 -0
  79. package/dist/resources/index.js.map +1 -0
  80. package/dist/schemas/kelviq.d.ts +1304 -0
  81. package/dist/schemas/kelviq.js +468 -0
  82. package/dist/schemas/kelviq.js.map +1 -0
  83. package/dist/server.d.ts +2 -0
  84. package/dist/server.js +41 -0
  85. package/dist/server.js.map +1 -0
  86. package/dist/tools/_util.d.ts +15 -0
  87. package/dist/tools/_util.js +15 -0
  88. package/dist/tools/_util.js.map +1 -0
  89. package/dist/tools/checkout.d.ts +3 -0
  90. package/dist/tools/checkout.js +18 -0
  91. package/dist/tools/checkout.js.map +1 -0
  92. package/dist/tools/customers.d.ts +3 -0
  93. package/dist/tools/customers.js +32 -0
  94. package/dist/tools/customers.js.map +1 -0
  95. package/dist/tools/docs.d.ts +2 -0
  96. package/dist/tools/docs.js +43 -0
  97. package/dist/tools/docs.js.map +1 -0
  98. package/dist/tools/entitlements.d.ts +3 -0
  99. package/dist/tools/entitlements.js +22 -0
  100. package/dist/tools/entitlements.js.map +1 -0
  101. package/dist/tools/features.d.ts +3 -0
  102. package/dist/tools/features.js +55 -0
  103. package/dist/tools/features.js.map +1 -0
  104. package/dist/tools/index.d.ts +3 -0
  105. package/dist/tools/index.js +44 -0
  106. package/dist/tools/index.js.map +1 -0
  107. package/dist/tools/licenses.d.ts +3 -0
  108. package/dist/tools/licenses.js +44 -0
  109. package/dist/tools/licenses.js.map +1 -0
  110. package/dist/tools/media.d.ts +3 -0
  111. package/dist/tools/media.js +18 -0
  112. package/dist/tools/media.js.map +1 -0
  113. package/dist/tools/offerings.d.ts +3 -0
  114. package/dist/tools/offerings.js +21 -0
  115. package/dist/tools/offerings.js.map +1 -0
  116. package/dist/tools/partner.d.ts +3 -0
  117. package/dist/tools/partner.js +55 -0
  118. package/dist/tools/partner.js.map +1 -0
  119. package/dist/tools/plan-entitlements.d.ts +3 -0
  120. package/dist/tools/plan-entitlements.js +56 -0
  121. package/dist/tools/plan-entitlements.js.map +1 -0
  122. package/dist/tools/plan-files.d.ts +3 -0
  123. package/dist/tools/plan-files.js +43 -0
  124. package/dist/tools/plan-files.js.map +1 -0
  125. package/dist/tools/plans.d.ts +3 -0
  126. package/dist/tools/plans.js +120 -0
  127. package/dist/tools/plans.js.map +1 -0
  128. package/dist/tools/portal.d.ts +3 -0
  129. package/dist/tools/portal.js +18 -0
  130. package/dist/tools/portal.js.map +1 -0
  131. package/dist/tools/product-files.d.ts +3 -0
  132. package/dist/tools/product-files.js +31 -0
  133. package/dist/tools/product-files.js.map +1 -0
  134. package/dist/tools/product-settings.d.ts +3 -0
  135. package/dist/tools/product-settings.js +31 -0
  136. package/dist/tools/product-settings.js.map +1 -0
  137. package/dist/tools/products.d.ts +3 -0
  138. package/dist/tools/products.js +69 -0
  139. package/dist/tools/products.js.map +1 -0
  140. package/dist/tools/promotions.d.ts +3 -0
  141. package/dist/tools/promotions.js +19 -0
  142. package/dist/tools/promotions.js.map +1 -0
  143. package/dist/tools/subscriptions.d.ts +3 -0
  144. package/dist/tools/subscriptions.js +63 -0
  145. package/dist/tools/subscriptions.js.map +1 -0
  146. package/dist/tools/usage.d.ts +3 -0
  147. package/dist/tools/usage.js +18 -0
  148. package/dist/tools/usage.js.map +1 -0
  149. 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
+ ---