@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,434 @@
1
+ ---
2
+ title: "Configuration & Customization"
3
+ slug: "checkout/checkout-configuration"
4
+ section: "checkout"
5
+ description: "Configure and customize checkout experiences for your customers"
6
+ ---
7
+ Checkout in Kelviq allows you to collect payments from customers. You can generate checkout links for your products, customize the checkout experience, and support multiple payment options and billing periods.
8
+
9
+ ## Overview
10
+ Kelviq's checkout system:
11
+ - **Powers your sales** - Collect payments and create customer subscriptions
12
+ - **Integrates with Stripe** - Uses Stripe as the payment processor
13
+ - **Highly configurable** - Control plans, pricing, trial periods, and more
14
+ - **Multi-currency ready** - Support customers worldwide
15
+ - **Easy to embed** - Generate links for any product and plans
16
+
17
+ ## Generating Checkout Links
18
+
19
+ Checkout links are generated at the **product level**. Each link can include one or more plans.
20
+
21
+ <img height="200" src="/images/accessing-checkout.png" />
22
+
23
+ ### Quick Start
24
+
25
+ 1. **Go to Products** → Select your product
26
+ 2. **Click "Generate Checkout Link"** → Opens the link builder
27
+ 3. **Select plans** → Choose which plans to include
28
+ 4. **Configure options** → Set defaults and features
29
+ 5. **Copy link** → Share with customers
30
+
31
+ <img height="200" src="/images/generate-checkout.png" />
32
+
33
+ ### Link Format
34
+
35
+ Generated checkout links follow this pattern:
36
+
37
+ ```
38
+ https://checkout.kelviq.com/products/{PRODUCT_ID}
39
+ ?enabled={PLAN_1_ID},{PLAN_2_ID}
40
+ &plan_identifier={DEFAULT_PLAN_ID}
41
+ &charge_period={DEFAULT_PERIOD}
42
+ ```
43
+
44
+ Example:
45
+ ```
46
+ https://checkout.kelviq.com/products/prod_abc123
47
+ ?enabled=plan_basic,plan_pro
48
+ &plan_identifier=plan_pro
49
+ &charge_period=monthly
50
+ ```
51
+
52
+ ## Multi-Plan Checkout
53
+
54
+ Include multiple plans in a single checkout to let customers choose their tier.
55
+
56
+ ### Configuration
57
+
58
+ **Plans Configuration**
59
+ - Select which plans are enabled (shown to customer)
60
+ - Choose a recommended plan (highlighted by default)
61
+ - Cannot disable all plans
62
+ - Disabled plans don't appear in checkout
63
+
64
+ ### Example: Multi-Plan Pricing
65
+
66
+ Your product has 3 plans: Free, Pro, Enterprise
67
+
68
+ ```
69
+ Plan 1: Free
70
+ ├─ Enabled: Yes
71
+ ├─ Price: $0/month
72
+ └─ Show in checkout: Yes
73
+
74
+ Plan 2: Pro (Recommended)
75
+ ├─ Enabled: Yes
76
+ ├─ Price: $29/month
77
+ └─ Show in checkout: Yes (selected by default)
78
+
79
+ Plan 3: Enterprise
80
+ ├─ Enabled: Yes
81
+ ├─ Price: Custom quote
82
+ └─ Show in checkout: Yes
83
+ ```
84
+
85
+ Generated checkout URL:
86
+ ```
87
+ ?enabled=free,pro,enterprise&plan_identifier=pro
88
+ ```
89
+
90
+ ## Billing Periods & Pricing
91
+
92
+ ### Supported Billing Periods
93
+
94
+ Plans in Kelviq can support multiple billing periods:
95
+
96
+ | Period | Duration | Use Case |
97
+ |--------|----------|----------|
98
+ | **Monthly** | 1 month | Recurring subscriptions |
99
+ | **3 Months** | 3 months | Quarterly billing |
100
+ | **Yearly** | 12 months | Annual billing, often with discounts |
101
+ | **One Time** | One-off payment | Digital products, courses, lifetime access |
102
+
103
+ ### Setting Default Billing Period
104
+
105
+ Configure which billing period is pre-selected for each plan:
106
+
107
+ ```
108
+ Plan: Pro
109
+ ├─ Monthly: $29/month (default for checkout)
110
+ ├─ Yearly: $290/year (saves $58)
111
+ └─ Checkout pre-selects: Monthly
112
+ ```
113
+
114
+ In your checkout link:
115
+ ```
116
+ &charge_period=monthly
117
+ ```
118
+
119
+ ### Pricing by Period
120
+
121
+ Different plans can have different pricing for the same period:
122
+
123
+ ```
124
+ Plan: Basic
125
+ ├─ Monthly: $9/month
126
+ └─ Yearly: $90/year
127
+
128
+ Plan: Pro
129
+ ├─ Monthly: $29/month
130
+ └─ Yearly: $290/year (2.5% discount vs monthly)
131
+
132
+ Plan: Enterprise
133
+ ├─ Monthly: $99/month
134
+ └─ Yearly: $999/year (16% discount vs monthly)
135
+ ```
136
+
137
+ Customers see all options and can choose their preferred period at checkout.
138
+
139
+ ## Free Trials
140
+
141
+ Offer free trial periods before charging customers.
142
+
143
+ ### Configuring Trials
144
+
145
+ 1. **Open your plan** → Go to the plan's pricing section
146
+ 2. **Enable Free Trial** → Toggle the trial option
147
+ 3. **Set duration** → 1-365 days (default 30)
148
+ 4. **Save plan**
149
+
150
+ ### Trial Behavior
151
+
152
+ When a customer starts a trial:
153
+
154
+ ```
155
+ Timeline:
156
+ Day 0: Customer signs up, trial begins
157
+ Days 1-30: Customer has full access, no charge
158
+ Day 30: Trial ends, first billing occurs
159
+ Day 31+: Regular subscription
160
+ ```
161
+
162
+ ### Trial Configuration Example
163
+
164
+ ```
165
+ Plan: Professional
166
+ ├─ Regular price: $29/month
167
+ ├─ Free trial: 30 days
168
+ ├─ After trial: Full charge of $29
169
+ └─ Customer can cancel anytime during trial
170
+ ```
171
+
172
+ Trials reduce payment friction. Customers are more likely to convert from trial to paid if they've experienced value.
173
+
174
+ ## Advanced Checkout Configuration
175
+
176
+ ### Custom Return URL
177
+
178
+ After checkout succeeds, redirect customers to your custom URL:
179
+
180
+ ```
181
+ Customer completes purchase
182
+ ↓
183
+ Kelviq redirects to your success page
184
+ ↓
185
+ You can:
186
+ - Show confirmation
187
+ - Deliver files/licenses
188
+ - Set up their account
189
+ - Continue onboarding
190
+ ```
191
+
192
+ Configure in your checkout link via API or dashboard:
193
+ ```
194
+ &return_url=https://yourdomain.com/checkout-success
195
+ ```
196
+
197
+ ### Discount Code Integration
198
+
199
+ Allow customers to apply discount codes at checkout:
200
+
201
+ <img height="200" src="/images/generate-checkout-discounts.png" />
202
+
203
+ ```
204
+ Customer at checkout:
205
+ 1. Select plan and period
206
+ 2. (Optional) Enter discount code
207
+ 3. See adjusted price
208
+ 4. Complete payment
209
+ ```
210
+
211
+ Discount codes are applied automatically if the customer enters a valid code.
212
+
213
+ ### Tax Collection
214
+
215
+ Kelviq can collect and handle taxes:
216
+
217
+ **Tax ID Collection:**
218
+ - Customers can enter their tax ID (VAT number, EIN, etc.)
219
+ - Used to determine applicable taxes
220
+ - Required for some jurisdictions
221
+
222
+ **Configuration:**
223
+ - Enable/disable tax collection per product
224
+ - Taxes are calculated based on customer location and tax ID
225
+
226
+ ### Country Restrictions
227
+
228
+ Restrict plans to specific countries:
229
+
230
+ ```
231
+ Plan: Premium Tier
232
+ ├─ Available countries: US, UK, CA, AU
233
+ ├─ Restricted countries: China, Russia
234
+ └─ Checkout effect: Plan hidden for customers in restricted countries
235
+ ```
236
+
237
+ ## Checkout Session Lifecycle
238
+
239
+ Checkout sessions track the state of each checkout attempt:
240
+
241
+ ### Session States
242
+
243
+ ```
244
+ open
245
+ ├─ Customer is in checkout
246
+ ├─ No payment yet
247
+ └─ Session expires after 24 hours
248
+
249
+ ↓
250
+
251
+ success
252
+ ├─ Payment completed
253
+ ├─ Customer created (if new)
254
+ ├─ Subscription created
255
+ └─ Files and licenses delivered
256
+
257
+ OR
258
+
259
+ closed
260
+ ├─ Customer abandoned checkout
261
+ ├─ No payment processed
262
+ ├─ Customer can restart
263
+ └─ Session expired
264
+ ```
265
+
266
+ ### Monitoring Checkouts
267
+
268
+ View checkout sessions in the dashboard:
269
+
270
+ <img height="200" src="/images/checkout-sessions.png" />
271
+
272
+ 1. **Go to Sales** → Checkout sessions
273
+ 2. **View sessions** → See all active and completed checkouts
274
+ 3. **Filter by status** → Open, Success, Closed, Expired
275
+ 4. **Conversion metrics** → Track conversion rates
276
+
277
+ <img height="200" src="/images/checkout-sessions-detials.png" />
278
+
279
+ ### Create Checkout Sessions via API
280
+
281
+ You can programmatically create checkout sessions using the SDK:
282
+
283
+
284
+
285
+ ```python
286
+ from kelviq_sdk import Kelviq
287
+
288
+ client = Kelviq.create_sync_client(access_token="your_server_api_key")
289
+
290
+ # Create a checkout session
291
+ response = client.checkout.create_session(
292
+ planIdentifier="plan-pro-monthly",
293
+ chargePeriod="MONTHLY",
294
+ customerId="cust_123",
295
+ successUrl="https://yoursite.com/checkout/success"
296
+ )
297
+
298
+ print(f"Checkout URL: {response.checkoutUrl}")
299
+ print(f"Session ID: {response.checkoutSessionId}")
300
+ ```
301
+
302
+
303
+
304
+
305
+ ```typescript
306
+ import { Kelviq, CHARGE_PERIOD_CHOICES } from '@kelviq/node-sdk';
307
+
308
+ const client = new Kelviq({ accessToken: 'your_server_api_key' });
309
+
310
+ // Create a checkout session
311
+ const response = await client.checkout.createSession({
312
+ planIdentifier: "plan-pro-monthly",
313
+ chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
314
+ customerId: "cust_123",
315
+ successUrl: "https://yoursite.com/checkout/success"
316
+ });
317
+
318
+ console.log(`Checkout URL: ${response.checkoutUrl}`);
319
+ console.log(`Session ID: ${response.checkoutSessionId}`);
320
+ ```
321
+
322
+
323
+ ## Checkout Flow Examples
324
+
325
+ ### Example 1: Simple Product
326
+
327
+ One plan, one price:
328
+
329
+ ```
330
+ Product: My Course
331
+ ├─ Plan: Full Access ($49)
332
+ └─ Billing: One-time payment
333
+
334
+ Link: ?enabled=full_access&plan_identifier=full_access&charge_period=one_time
335
+ ```
336
+
337
+ ### Example 2: Tiered Plans
338
+
339
+ Multiple plans, multiple billing periods:
340
+
341
+ ```
342
+ Product: Pro Templates
343
+ ├─ Plan 1: Starter ($9/month or $90/year)
344
+ ├─ Plan 2: Professional ($29/month or $290/year)
345
+ └─ Plan 3: Enterprise (Custom pricing)
346
+
347
+ Link: ?enabled=starter,pro,enterprise
348
+ &plan_identifier=pro
349
+ &charge_period=monthly
350
+ ```
351
+
352
+ ### Example 3: Free + Paid
353
+
354
+ Offer free plan with paid upgrades:
355
+
356
+ ```
357
+ Product: Productivity App
358
+ ├─ Plan 1: Free (no payment)
359
+ └─ Plan 2: Premium ($9.99/month with 30-day trial)
360
+
361
+ Link: ?enabled=free,premium
362
+ &plan_identifier=free
363
+ &charge_period=monthly
364
+ ```
365
+
366
+ ## Payment Methods
367
+
368
+ Kelviq uses **Stripe** as its payment processor. Stripe supports:
369
+
370
+ - **Credit/Debit Cards** - Visa, Mastercard, American Express, Discover
371
+ - **Digital Wallets** - Apple Pay, Google Pay
372
+ - **Bank Transfers** - ACH, SEPA, etc. (regional)
373
+ - **Local Methods** - iDEAL, Bancontact, Giropay, EPS (regional)
374
+
375
+ Customers select their preferred payment method at checkout.
376
+
377
+ Payment method availability depends on customer location and Stripe's local support. Cards are universally supported.
378
+
379
+ ## Currency & Localization
380
+
381
+ ### Multi-Currency Support
382
+
383
+ Prices are stored per currency. When customers checkout:
384
+
385
+ ```
386
+ Customer from EU viewing checkout:
387
+ - Product prices shown in EUR
388
+ - Customer sees "29,99 EUR"
389
+
390
+ Customer from US viewing same product:
391
+ - Product prices shown in USD
392
+ - Customer sees "$29.99"
393
+ ```
394
+
395
+ ### Pricing Configuration
396
+
397
+ Set prices for each currency you support:
398
+
399
+ ```
400
+ Plan: Pro
401
+ ├─ USD: $29/month
402
+ ├─ EUR: €27/month
403
+ ├─ GBP: £25/month
404
+ └─ AUD: A$45/month
405
+ ```
406
+
407
+ ### Regional Pricing
408
+
409
+ Offer different prices based on customer location (PPP - Purchasing Power Parity):
410
+
411
+ ```
412
+ Plan: Professional ($29 in US)
413
+ ├─ India: ₹599 (auto-adjusted for PPP)
414
+ ├─ Brazil: R$99
415
+ └─ US: $29
416
+ ```
417
+
418
+ ## Testing Checkout
419
+
420
+ ### Sandbox Testing
421
+
422
+ Test checkouts without processing real payments:
423
+
424
+ 1. **Use Stripe test cards** → Use 4242 4242 4242 4242
425
+ 2. **Test various scenarios** → Successful payment, declined card, etc.
426
+ 3. **Monitor test checkouts** → View in your dashboard
427
+
428
+ ### Test Card Examples
429
+
430
+ | Card | Result |
431
+ |------|--------|
432
+ | 4242 4242 4242 4242 | Successful payment |
433
+ | 4000 0000 0000 0002 | Card declined |
434
+ | 4000 0025 0000 3155 | Requires authentication |
@@ -0,0 +1,111 @@
1
+ ---
2
+ title: "Overview"
3
+ slug: "coustomers-management/overview"
4
+ section: "coustomers-management"
5
+ description: "View and manage customer details, subscriptions, and entitlements."
6
+ ---
7
+ Managing customers sits at the center of Kelviq. Each customer connects directly to their subscriptions, the plans behind them, and the features they own. You need to understand these relationships to handle the full customer lifecycle.
8
+
9
+ ## View customer list
10
+
11
+ Select **Customers** in the main navigation to see your list.
12
+
13
+ You can do a few things here.
14
+ * **Search** by name, email, or identifier.
15
+ * **Add a new customer** with the button in the top right.
16
+ * **Manage a customer** by clicking their row to see details.
17
+
18
+ <img height="200" src="/images/customers-list.png" />
19
+
20
+ ## Add a new customer
21
+
22
+ You can create records manually.
23
+
24
+
25
+
26
+ Click **+ New customer** in the top right of the list page.
27
+
28
+
29
+
30
+
31
+ You need to provide a few key pieces of info.
32
+ * **Customer name** is required. Use the person's full name or company name.
33
+ * **Identifier** is the unique ID the API uses. We auto-generate this based on the name, but you can edit it. Linking this to the ID in your own database is usually a good idea.
34
+ * **Email address** is optional.
35
+
36
+
37
+
38
+
39
+ Click **Create** to finish.
40
+
41
+ If you are adding a batch of people, toggle on **Create more**. This keeps the window open so you can add the next one immediately.
42
+
43
+
44
+ <img height="200" src="/images/create-customer-modal.png" />
45
+
46
+ ## Manage existing customers
47
+
48
+ You can edit details or revoke access from the list view.
49
+
50
+ ### Edit a customer
51
+ Click the **three dots** on the right side of the customer row and select **Edit**.
52
+
53
+ <img height="200" src="/images/edit-customer.png" />
54
+
55
+ You can update the **Customer name** and **Email address**. The Identifier is fixed after creation and cannot be changed.
56
+
57
+ ### Archive a customer
58
+ Archiving makes a customer inactive and revokes their access. Click the **three dots** and select **Archive**.
59
+
60
+ <img height="200" src="/images/archive-customer.png" />
61
+
62
+ You will see a confirmation warning. Click **Confirm** to proceed.
63
+
64
+ You cannot archive a customer with an active subscription. You must cancel their subscription first.
65
+
66
+ ## Customer details
67
+
68
+ Click on any customer row to open their full profile.
69
+
70
+ This page holds the source of truth for that user. You can see their unique Billing ID and timestamps for when they joined or were last updated.
71
+
72
+ <img height="200" src="/images/customer-details.png" />
73
+
74
+ ### Subscriptions
75
+
76
+ This section lists active and past plans. It shows the status, such as Active or Canceled, and the relevant dates.
77
+
78
+ **Add a subscription**
79
+ You can manually subscribe a customer to a plan from here.
80
+
81
+ <img height="200" src="/images/add-subscription.png" />
82
+
83
+ 1. Click **Add subscription**.
84
+ 2. Set the **Billing period** and **Currency**.
85
+ 3. Select the **Features** included in this specific sub.
86
+ 4. Set the **Usage limits** or allowances.
87
+ 5. Choose a **Start date**. You can also adjust the **Free trial** period here.
88
+
89
+ **Edit a subscription**
90
+ You can also modify an existing subscription. Click on the subscription card to update terms, change status, or extend trial dates.
91
+
92
+ ### Entitlements
93
+
94
+ This view shows exactly what the customer can do right now based on their plan.
95
+
96
+ **Overrides**
97
+ You often need to make exceptions for specific users. You can do that here without changing the underlying plan.
98
+ * Change the value of a specific feature.
99
+ * Update the usage limit for a metered feature.
100
+
101
+ Changes made here apply only to this specific customer.
102
+
103
+ <img height="200" src="/images/entitlements-details.png" />
104
+
105
+ ### Usage
106
+
107
+ This tracks consumption for usage-based billing.
108
+ * Graphs show usage trends over time.
109
+ * Hover over the data to see exact numbers for specific periods.
110
+
111
+ <img height="200" src="/images/entitlements-full-details.png" />
@@ -0,0 +1,81 @@
1
+ ---
2
+ title: "Customer portal"
3
+ slug: "customer-portal/overview"
4
+ section: "customer-portal"
5
+ description: "A self-serve hub for your customers to manage subscriptions and access content."
6
+ ---
7
+ Kelviq provides a hosted customer portal.
8
+
9
+ This is a self-serve environment. Your customers manage their own subscriptions, access files, and handle billing details. You don't need to build this. It ensures you don't have to manually answer support tickets for basic tasks like upgrading plans or downloading invoices.
10
+
11
+ ## Access and login
12
+
13
+ The portal uses passwordless, secure access.
14
+
15
+
16
+
17
+ When a customer completes a purchase, they get access immediately.
18
+
19
+
20
+
21
+
22
+ Customers enter their email address on your portal login page.
23
+
24
+
25
+
26
+
27
+ We send a one-time access code to their email. They enter this code to log in. No passwords to remember.
28
+
29
+
30
+ <img height="200" src="/images/portal-login.png" />
31
+
32
+ ## My orders
33
+
34
+ This is the home screen. It lists everything the customer owns. They can click on a specific product to see details.
35
+
36
+ <img height="200" src="/images/orders-list.png" />
37
+
38
+ ### Product details
39
+ Inside a specific product, customers find their deliverables.
40
+
41
+ * **Digital downloads**
42
+ Access files, e-books, or software binaries.
43
+ * **External links**
44
+ Private links to Discord servers or Notion templates.
45
+ * **License management**
46
+ View license keys. If you enforce seat limits, customers can see active devices and revoke licenses to free up seats for new team members.
47
+
48
+ <img height="200" src="/images/product-downloads.png" />
49
+
50
+ ## Subscription management
51
+
52
+ Customers have control over their lifecycle without contacting you.
53
+
54
+ * **Change plans**
55
+ Upgrade to a higher tier or downgrade.
56
+ * **Pause and cancel**
57
+ Pause a subscription temporarily or stop it entirely.
58
+ * **Payment methods**
59
+ Update credit card details or switch methods for future renewals.
60
+
61
+ <img height="200" src="/images/update-payment-modal.png" />
62
+
63
+ ## Billing settings
64
+
65
+ This section handles compliance and admin tasks.
66
+
67
+ ### Invoices and receipts
68
+ Customers can view their full payment history. They can download PDF invoices and receipts for their own accounting.
69
+
70
+ <img height="200" src="/images/invoices-tab.png" />
71
+
72
+ ### Account details
73
+ This is where they manage the legal side of the account.
74
+ * **Tax IDs**
75
+ Update billing addresses and VAT/Tax IDs.
76
+ * **Refund status**
77
+ Track the status of partial or full refunds.
78
+ * **Account transfer**
79
+ Transfer ownership of the account and subscription to a different email address.
80
+
81
+ <img height="200" src="/images/billing-settings.png" />