@kelviq/mcp-server 1.2.1 → 1.3.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 (101) hide show
  1. package/README.md +40 -3
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +1 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/ai/docs-for-agents.md +21 -0
  6. package/dist/docs/ai/overview.md +43 -0
  7. package/dist/docs/api-reference/authentication.md +9 -3
  8. package/dist/docs/api-reference/introduction.md +23 -2
  9. package/dist/docs/backend-integration/node-sdk.md +12 -6
  10. package/dist/docs/backend-integration/python-sdk.md +14 -8
  11. package/dist/docs/changelog.md +352 -3
  12. package/dist/docs/checkout/checkout-configuration.md +25 -75
  13. package/dist/docs/checkout/checkout-design.md +76 -0
  14. package/dist/docs/checkout/checkout-examples.md +212 -0
  15. package/dist/docs/checkout/checkout-metadata.md +1 -1
  16. package/dist/docs/checkout/custom-fields.md +60 -0
  17. package/dist/docs/checkout/embed-checkout.md +280 -0
  18. package/dist/docs/checkout/payment-methods/upi.md +69 -0
  19. package/dist/docs/checkout/payment-methods.md +119 -0
  20. package/dist/docs/checkout/static-checkout-url.md +3 -2
  21. package/dist/docs/cli/commands.md +57 -4
  22. package/dist/docs/cli/kelviq-config.md +1 -1
  23. package/dist/docs/cli/overview.md +1 -0
  24. package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
  25. package/dist/docs/customer-portal/overview.md +7 -7
  26. package/dist/docs/customer-portal/retention.md +109 -0
  27. package/dist/docs/customers-management/overview.md +105 -0
  28. package/dist/docs/frontend-integration/js-sdk.md +11 -11
  29. package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
  30. package/dist/docs/frontend-integration/react-sdk.md +8 -49
  31. package/dist/docs/frontend-integration/react-ui.md +8 -6
  32. package/dist/docs/getstarted/fees.md +27 -11
  33. package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
  34. package/dist/docs/getstarted/merchant-of-record.md +18 -24
  35. package/dist/docs/getstarted/overview.md +98 -0
  36. package/dist/docs/getstarted/review-process.md +59 -59
  37. package/dist/docs/guides/agent-toolkit.md +14 -9
  38. package/dist/docs/guides/mcp-server.md +24 -9
  39. package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
  40. package/dist/docs/guides/sandbox.md +6 -4
  41. package/dist/docs/guides/set-up-with-ai.md +43 -0
  42. package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
  43. package/dist/docs/guides/subscription-integration.md +1 -1
  44. package/dist/docs/guides/test-payments.md +640 -0
  45. package/dist/docs/guides/webhooks.md +182 -30
  46. package/dist/docs/integrations/woocommerce.md +88 -0
  47. package/dist/docs/integrations/zapier.md +22 -0
  48. package/dist/docs/legal/account-and-funds.md +59 -0
  49. package/dist/docs/legal/approved-prohibited-policy.md +32 -27
  50. package/dist/docs/legal/payment-flow-diagram.md +7 -7
  51. package/dist/docs/manifest.json +160 -41
  52. package/dist/docs/openapi.json +1359 -109
  53. package/dist/docs/payouts/overview.md +14 -12
  54. package/dist/docs/payouts/payout-account.md +1 -1
  55. package/dist/docs/payouts/transactions.md +3 -3
  56. package/dist/docs/product-catalog/create-a-feature.md +3 -3
  57. package/dist/docs/product-catalog/digital-downloads.md +5 -5
  58. package/dist/docs/product-catalog/discounts.md +2 -2
  59. package/dist/docs/product-catalog/entitlements.md +20 -27
  60. package/dist/docs/product-catalog/free-and-trials.md +4 -4
  61. package/dist/docs/product-catalog/license-keys.md +56 -29
  62. package/dist/docs/product-catalog/links.md +3 -3
  63. package/dist/docs/product-catalog/location-based-pricing.md +6 -10
  64. package/dist/docs/product-catalog/one-time-payments.md +3 -7
  65. package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
  66. package/dist/docs/product-catalog/plans.md +22 -19
  67. package/dist/docs/product-catalog/products.md +11 -3
  68. package/dist/docs/product-catalog/proration.md +69 -0
  69. package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
  70. package/dist/docs/product-catalog/subscriptions.md +52 -22
  71. package/dist/docs/product-catalog/tax-settings.md +8 -8
  72. package/dist/docs/product-catalog/usage-alerts.md +7 -7
  73. package/dist/docs/product-catalog/usage-based-billing.md +156 -29
  74. package/dist/docs/product-catalog/usage-limits.md +78 -0
  75. package/dist/docs/promotions/create-a-promotion.md +2 -2
  76. package/dist/docs/promotions/overview.md +1 -1
  77. package/dist/docs/quickstart/core-concepts.md +36 -30
  78. package/dist/docs/quickstart/dashboard-setup.md +26 -22
  79. package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
  80. package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
  81. package/dist/docs/sales/checkout-sessions.md +28 -39
  82. package/dist/docs/sales/orders.md +30 -54
  83. package/dist/docs/settings/customer-emails.md +52 -0
  84. package/dist/docs/settings/members.md +27 -0
  85. package/dist/docs/settings/profile.md +26 -0
  86. package/dist/docs/settings/zapier.md +22 -0
  87. package/dist/http/errors.d.ts +20 -1
  88. package/dist/http/errors.js +83 -31
  89. package/dist/http/errors.js.map +1 -1
  90. package/dist/schemas/kelviq.d.ts +54 -0
  91. package/dist/schemas/kelviq.js +64 -0
  92. package/dist/schemas/kelviq.js.map +1 -1
  93. package/dist/server.js +3 -2
  94. package/dist/server.js.map +1 -1
  95. package/dist/tools/imports.d.ts +68 -0
  96. package/dist/tools/imports.js +242 -0
  97. package/dist/tools/imports.js.map +1 -0
  98. package/dist/tools/index.d.ts +2 -1
  99. package/dist/tools/index.js +4 -1
  100. package/dist/tools/index.js.map +1 -1
  101. package/package.json +1 -1
@@ -1,42 +1,119 @@
1
1
  ---
2
- title: "Usage based pricing"
2
+ title: "Usage-based pricing"
3
3
  slug: "product-catalog/usage-based-billing"
4
4
  section: "product-catalog"
5
5
  description: "Charge customers for the actual work your product performs"
6
6
  ---
7
- AI products perform actual work. Flat rate subscriptions force you to guess at average compute costs which destroys your margins. Usage based pricing lets you charge for exact consumption.
7
+ Usage-based pricing charges customers for what they use: API calls, tokens, compute, or any other Meter feature.
8
8
 
9
9
  ## Set up a usage plan
10
10
 
11
- To add consumption tracking to a plan, open its pricing configuration and expand **Usage charges**.
12
-
13
- <img height="200" src="/images/usage-pricing-card.png" />
14
-
15
- ### 1. Select or create a metered feature
11
+ The example below is a **Pro** plan: \$29 a month, 10,000 API calls included, then \$0.002 per call. [How usage limits work](/product-catalog/usage-limits) explains what happens at the limit.
12
+
13
+
14
+
15
+ Open the plan's pricing and expand **Usage charges**, then follow the steps below.
16
+
17
+
18
+
19
+ <img src="/images/usage-pricing-card.webp" />
20
+
21
+
22
+
23
+
24
+
25
+
26
+ Define the plan in `kelviq.config.ts`. The entitlement sets the included 10,000 calls. The Pay as you go price bills calls past that at the end of each month.
27
+
28
+ ```ts kelviq.config.ts
29
+ import { feature, plan } from '@kelviq/cli/config';
30
+
31
+ export const apiCalls = feature({
32
+ identifier: 'api-calls',
33
+ name: 'API calls',
34
+ type: 'METER',
35
+ featureDetails: {
36
+ featureSubType: 'PRE_AGGREGATED_USAGE',
37
+ units: { singular: 'call', plural: 'calls' },
38
+ },
39
+ });
40
+
41
+ export const pro = plan({
42
+ identifier: 'pro',
43
+ name: 'Pro',
44
+ product: 'my-app',
45
+ entitlements: [
46
+ { feature: 'api-calls', value: 10000, reset: 'EVERY_MONTH', hardLimit: false },
47
+ ],
48
+ prices: [
49
+ {
50
+ priceType: 'PAID',
51
+ currency: 'USD',
52
+ chargeCatalogPrice: [
53
+ {
54
+ feature: null,
55
+ priceModel: 'FLAT',
56
+ paymentType: 'ADVANCE_COMMITMENT',
57
+ reset: 'NEVER',
58
+ charges: [{ chargePeriod: 'MONTHLY', priceData: { amount: 29 } }],
59
+ },
60
+ {
61
+ feature: 'api-calls',
62
+ priceModel: 'TIERED',
63
+ paymentType: 'PAY_AS_YOU_GO',
64
+ reset: 'EVERY_MONTH',
65
+ charges: [
66
+ {
67
+ chargePeriod: 'MONTHLY',
68
+ priceData: { currency: 'USD' },
69
+ tiers: [
70
+ { upTo: 10000, unitAmount: 0, flatAmount: 0 },
71
+ { upTo: 'inf', unitAmount: 0.002, flatAmount: 0 },
72
+ ],
73
+ },
74
+ ],
75
+ },
76
+ ],
77
+ },
78
+ ],
79
+ });
80
+ ```
81
+
82
+ Preview the change, then push and publish it:
83
+
84
+ ```bash
85
+ npx kelviq push --dry-run
86
+ npx kelviq push --publish
87
+ ```
88
+
89
+ See the [CLI overview](/cli/overview) and the [config reference](/cli/kelviq-config).
90
+
91
+
92
+ ### 1. Select or create a Meter feature
16
93
 
17
94
  Choose the metric you want to track from the dropdown list, such as API requests or tokens consumed. If the list is empty, [create a Meter feature](/product-catalog/create-a-feature) from **Product catalog → Features**, then return to the plan.
18
95
 
19
- <img height="200" src="/images/select-metered-feature.png" />
96
+ <img src="/images/select-metered-feature.webp" />
20
97
 
21
98
  ### 2. Choose your billing model
22
99
 
23
100
  Select how payments are structured.
24
101
 
25
- <img height="200" src="/images/select-billing-model.png" />
102
+ <img src="/images/select-billing-model.webp" />
26
103
 
27
104
  **Advance commitment**
28
105
  Customers pay upfront for a baseline allotment of usage. This gives your users a predictable budget. They buy a set bucket of AI tokens or API requests at the start of the month. They consume what they paid for and avoid surprise overages.
29
106
 
30
107
  **Pay as you go**
31
- Customers pay for their recorded usage at the end of the monthly subscription period. You can bill for API calls, tokens, storage, compute time, or another metered feature, either on its own or alongside a monthly base price. See [Pay as you go](/product-catalog/pay-as-you-go) for setup, usage reporting, sandbox testing, and troubleshooting.
108
+ Customers pay for their recorded usage at the end of the monthly subscription period. You can bill for API calls, tokens, storage, compute time, or another Meter feature, either on its own or alongside a monthly base price. See [Pay as you go](/product-catalog/pay-as-you-go) for setup, usage reporting, sandbox testing, and troubleshooting.
32
109
 
33
- Monthly must be the plan's only billing period. Pay as you go does not support Stair-step pricing or credit rollover.
110
+ Pay as you go bills monthly from reported usage, so Monthly is the plan's only billing period. Stair-step pricing and credit rollover work with Advance commitment prices.
34
111
 
35
112
  ### 3. Configure the pricing model
36
113
 
37
114
  Kelviq supports five distinct ways to calculate the cost. Here is how the math works for each model.
38
115
 
39
- <img height="400" src="/images/usage-pricing-models.png" />
116
+ <img src="/images/usage-pricing-models.webp" />
40
117
 
41
118
  ---
42
119
 
@@ -46,7 +123,7 @@ The simplest way to charge for usage. Set one fixed rate for every unit consumed
46
123
 
47
124
  **Best for** API products and services where the cost of serving each unit stays relatively consistent.
48
125
 
49
- **Example** A translation API charging for each character processed.
126
+ **Example** A translation API charging for each API call.
50
127
 
51
128
  **Sample calculation**
52
129
 
@@ -56,7 +133,7 @@ The simplest way to charge for usage. Set one fixed rate for every unit consumed
56
133
  | Usage | 15,000 API calls |
57
134
  | **Total** | 15,000 × \$0.01 = **\$150** |
58
135
 
59
- <img height="400" src="/images/flat-pricing.png" />
136
+ <img src="/images/flat-pricing.webp" />
60
137
 
61
138
  ---
62
139
 
@@ -77,7 +154,7 @@ Instead of charging for every unit individually you sell usage in predefined pac
77
154
  | Packages required | 3 |
78
155
  | **Total** | 3 × \$10 = **\$30** |
79
156
 
80
- <img height="400" src="/images/package-pricing.png" />
157
+ <img src="/images/package-pricing.webp" />
81
158
 
82
159
  ---
83
160
 
@@ -104,9 +181,9 @@ A customer uses 3,500 tokens.
104
181
  | Tier 2 | 2,500 × \$0.05 = \$125 |
105
182
  | **Total** | \$100 + \$125 = **\$225** |
106
183
 
107
- Kelviq tracks each pricing bracket automatically, with sub-100ms real-time access checks.
184
+ Kelviq tracks each pricing bracket automatically.
108
185
 
109
- <img height="400" src="/images/tiered-pricing.png" />
186
+ <img src="/images/tiered-pricing.webp" />
110
187
 
111
188
  ---
112
189
 
@@ -134,7 +211,7 @@ A customer makes 120,000 API calls.
134
211
 
135
212
  Kelviq automatically applies the correct rate when customers cross a volume threshold, with no custom billing logic required.
136
213
 
137
- <img height="400" src="/images/volume-pricing.png" />
214
+ <img src="/images/volume-pricing.webp" />
138
215
 
139
216
  ---
140
217
 
@@ -142,7 +219,7 @@ Kelviq automatically applies the correct rate when customers cross a volume thre
142
219
 
143
220
  Customers pay a fixed fee based on the usage bracket they fall into, regardless of the exact number of units used within that bracket. There is no per-unit rate.
144
221
 
145
- **Why it's useful** Combines the simplicity of subscription plans with the flexibility of usage-based scaling. Perfect for API plans, infrastructure products, and other services with clear usage bands.
222
+ **Why it's useful** Combines the simplicity of subscription plans with the flexibility of usage-based scaling.
146
223
 
147
224
  **Example** An email delivery platform charging based on monthly email volume.
148
225
 
@@ -157,7 +234,7 @@ A customer sends 12,000 emails. They fall into the second step and pay a flat **
157
234
 
158
235
  Kelviq automatically moves customers into the correct pricing step as their usage grows, with no custom billing logic required.
159
236
 
160
- <img height="400" src="/images/stair-step-pricing.png" />
237
+ <img src="/images/stair-step-pricing.webp" />
161
238
 
162
239
  ---
163
240
 
@@ -167,13 +244,13 @@ Once you pick a pricing model you define the exact boundaries.
167
244
 
168
245
  If you select Tiered you specify the first unit and last unit for each bucket. You can charge a per unit price and a flat fee within that same tier.
169
246
 
170
- You can also set localized pricing for usage based billing. This lets you define different per unit rates for specific countries and currencies.
247
+ You can also set localized pricing for usage-based pricing. This lets you define different per unit rates for specific countries and currencies.
171
248
 
172
- #### Regional pricing and usage controls
249
+ #### Price localization and usage controls
173
250
 
174
- When you add a regional price, Kelviq carries over the base price's usage reset, usage alert, and credit rollover settings. This keeps entitlement behavior consistent while allowing the monetary price and currency to vary by region.
251
+ When you add a localized price, Kelviq carries over the base price's usage reset, usage alert, and credit rollover settings. This keeps entitlement behavior consistent while allowing the monetary price and currency to vary by region.
175
252
 
176
- Update these controls on the base price when you want the same behavior across its regional prices.
253
+ Update these controls on the base price when you want the same behavior across its localized prices.
177
254
 
178
255
  ### 5. Set the usage reset cadence
179
256
 
@@ -191,14 +268,14 @@ Credit rollover lets a customer keep part of an advance commitment they did not
191
268
 
192
269
  To configure it:
193
270
 
194
- 1. In the plan editor, expand **Usage charges** and open the metered feature.
271
+ 1. In the plan editor, expand **Usage charges** and open the Meter feature.
195
272
  2. Choose **Advance commitment** as the billing model.
196
273
  3. Set the included **Value** and a recurring **Usage reset**.
197
274
  4. Turn on **Credit rollover**.
198
275
  5. Enter the **Percentage** of unused units to carry forward. The value can be from 0% to 100%.
199
276
  6. Enter a **Limit** in units to cap the rollover amount.
200
277
 
201
- <img height="400" src="/images/credits-rollover.png" />
278
+ <img src="/images/credits-rollover.webp" />
202
279
 
203
280
  For example, suppose a plan includes 10,000 credits each month. The customer has 2,000 credits left when the meter resets, and rollover is set to 50% with a 750-unit limit. Fifty percent of the unused balance is 1,000 credits, so the limit reduces the rollover to 750. The customer's next period starts with 10,750 credits.
204
281
 
@@ -206,16 +283,66 @@ For example, suppose a plan includes 10,000 credits each month. The customer has
206
283
 
207
284
  #### Usage alerts
208
285
 
209
- Usage alerts watch a metered feature for percentage or absolute-unit thresholds. When a customer crosses a threshold, Kelviq sends `feature.usage_alert` to your subscribed webhook endpoint. Your application can then send an email, show an in-app warning, or start an upgrade flow.
286
+ Usage alerts watch a Meter feature for percentage or absolute-unit thresholds. When a customer crosses a threshold, Kelviq sends `feature.usage_alert` to your subscribed webhook endpoint. Your application can then send an email, show an in-app warning, or start an upgrade flow.
210
287
 
211
288
  See [Usage alerts](/product-catalog/usage-alerts) for dashboard and API configuration, the webhook payload, a Node.js handler, and sandbox testing steps.
212
289
 
213
290
  ### 7. Stack multiple usage metrics
214
291
 
215
- <img height="400" src="/images/stack-multiple-usage-metrics.png" />
292
+ <img src="/images/stack-multiple-usage-metrics.webp" />
216
293
 
217
294
  AI products rarely track just one variable. You can add as many metered usage features as you want to a single plan. Just click the Add usage pricing button at the bottom of the section to set up another metric.
218
295
 
296
+ ## Check access and report usage
297
+
298
+ Report usage from your backend each time the feature is used, then check what's left before the next request.
299
+
300
+ ```ts Node
301
+ import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';
302
+
303
+ // Count one API call
304
+ await client.reporting.reportUsage({
305
+ customerId: 'cust_123',
306
+ featureId: 'api-calls',
307
+ value: 1,
308
+ behaviour: BEHAVIOUR_CHOICES.DELTA,
309
+ });
310
+
311
+ // Check what's left
312
+ const ent = await client.entitlements.getEntitlement({
313
+ customerId: 'cust_123',
314
+ featureId: 'api-calls',
315
+ });
316
+
317
+ if (!ent || (!ent.hasAccess && ent.hardLimit)) {
318
+ // No access, or a hard limit was reached: block or ask the customer to upgrade
319
+ }
320
+ // Past a soft limit, let the call through: it's billed as overage
321
+ ```
322
+
323
+ ```python Python
324
+ # Count one API call
325
+ client.reporting.report_usage(
326
+ customerId="cust_123",
327
+ featureId="api-calls",
328
+ value=1,
329
+ behaviour="DELTA",
330
+ )
331
+
332
+ # Check what's left
333
+ ent = client.entitlements.get_entitlement(
334
+ customerId="cust_123",
335
+ featureId="api-calls",
336
+ )
337
+
338
+ if not ent or (not ent.hasAccess and ent.hardLimit):
339
+ # No access, or a hard limit was reached: block or ask the customer to upgrade
340
+ ...
341
+ # Past a soft limit, let the call through: it's billed as overage
342
+ ```
343
+
344
+ `remaining` is the usage left in the current period. `hasAccess` turns `false` when it reaches 0; `hardLimit` tells you whether to block. See the [Node SDK](/backend-integration/node-sdk#entitlements) and [Python SDK](/backend-integration/python-sdk) for every method.
345
+
219
346
  ## Model a plan with different kinds of limits
220
347
 
221
348
  Not every plan limit should be a meter. Choose the feature type based on what the value means and how your application will use it.
@@ -230,6 +357,6 @@ Not every plan limit should be a meter. Choose the feature type based on what th
230
357
  | Analytics | Boolean | Enable on the plans that include it |
231
358
  | Priority support | Boolean | Enable on the plans that include it |
232
359
 
233
- For metered limits, consider usage alerts at 80% and 90%. These thresholds give customers time to reduce usage or upgrade before they reach a hard limit. Rollover and overage behavior depend on your pricing policy; do not enable them automatically for every meter.
360
+ For metered limits, consider usage alerts at 80% and 90%. These thresholds give customers time to reduce usage or upgrade before they reach a hard limit. Rollover and overage are optional; turn them on only where they fit your pricing. See [How usage limits work](/product-catalog/usage-limits).
234
361
 
235
362
  When a customer changes plans, Kelviq retains their existing usage counters and evaluates them against the new limits. A customer who has already consumed more than the downgraded limit may therefore become over limit as soon as the downgrade takes effect.
@@ -0,0 +1,78 @@
1
+ ---
2
+ title: "How usage limits work"
3
+ slug: "product-catalog/usage-limits"
4
+ section: "product-catalog"
5
+ description: "What a limit is, when usage resets, what happens when a customer reaches the limit, and how overage is billed"
6
+ ---
7
+ A usage limit is the amount of a Meter feature a plan includes, such as 10,000 API calls a month. Your app reports usage, Kelviq counts it against the limit, and your app checks what's left before letting the customer use more.
8
+
9
+ This page follows one example: the **Pro** plan of an AI app costs \$29 a month and includes 10,000 `api-calls`, reset monthly.
10
+
11
+ ## The terms
12
+
13
+ | Term | What it means |
14
+ | --- | --- |
15
+ | **Base fee** | The fixed price of the plan, charged each billing period whatever the usage. \$29 a month in the example. |
16
+ | **Meter feature** | A feature Kelviq counts, such as API calls, tokens, credits, or seats. |
17
+ | **Usage limit** | How much of a Meter feature the plan includes. Can be a number or unlimited. |
18
+ | **Current usage** | How much the customer has used since the last reset. |
19
+ | **Remaining** | Usage limit minus current usage. |
20
+ | **Reset** | When current usage goes back to 0. |
21
+ | **Hard limit** | Usage is blocked once the limit is reached. |
22
+ | **Soft limit** | Usage can go past the limit. Your app decides what to do, such as warn the customer or bill overage. |
23
+ | **Overage** | Usage past the included limit, billed at a per-unit rate. |
24
+ | **Customizable feature** | A number or setting per plan, such as max upload size or number of projects. Kelviq stores the value; it doesn't count usage against it. |
25
+
26
+ ## How usage is counted
27
+
28
+ Your backend reports usage for a customer and a Meter feature:
29
+
30
+ * `DELTA` adds to current usage. Send it each time something is used: one API call, 1,200 tokens.
31
+ * `SET` replaces current usage. Use it for numbers you already track, such as seats in use.
32
+
33
+ In the example, after 6,500 calls the customer's entitlement looks like this:
34
+
35
+ ```json
36
+ {
37
+ "featureId": "api-calls",
38
+ "featureType": "METER",
39
+ "hasAccess": true,
40
+ "hardLimit": true,
41
+ "usageLimit": 10000,
42
+ "currentUsage": 6500,
43
+ "remaining": 3500
44
+ }
45
+ ```
46
+
47
+ See [Features & limits](/product-catalog/entitlements#sdk-integration) for the SDK calls.
48
+
49
+ ## When usage resets
50
+
51
+ Each Meter feature on a plan has a **usage reset**: never, or a recurring period such as every hour, day, week, month, or year. For monthly resets you choose the first day of the month or the customer's subscription start date.
52
+
53
+ A reset of **Never** makes the limit a lifetime allowance. Credit packs work this way.
54
+
55
+ ## What happens at the limit
56
+
57
+ For a Meter feature, `hasAccess` is `true` while `remaining` is above 0 or the limit is unlimited.
58
+
59
+ * **Hard limit:** at 10,000 calls, `hasAccess` turns `false` and additional usage is stopped until the next reset or an upgrade.
60
+ * **Soft limit:** usage keeps counting past 10,000. `hasAccess` is also `false` here, so check `hardLimit` before blocking. If the plan has an overage price, let the customer continue and the extra usage is billed.
61
+
62
+ Use [usage alerts](/product-catalog/usage-alerts) to warn customers before they get there, for example at 80% and 90%.
63
+
64
+ ## Overage
65
+
66
+ To charge for usage past the included amount, add a **Pay as you go** usage price to the plan, for example a Tiered price whose first 10,000 calls are free and each call after that costs \$0.002. Kelviq bills the overage at the end of each monthly period from the usage you report. See [Pay as you go](/product-catalog/pay-as-you-go).
67
+
68
+ ## Rollover
69
+
70
+ With an **Advance commitment** price, part of the unused allowance can carry into the next period. In the example, with 50% rollover capped at 750, a customer who has 2,000 calls left at the reset starts the next month with 10,750. See [credit rollover](/product-catalog/usage-based-billing#credit-rollover).
71
+
72
+ ## Plan changes
73
+
74
+ When a customer upgrades or downgrades, the new plan's limits apply immediately and current usage is kept. A customer who used 6,500 calls and downgrades to a plan with 5,000 is over the limit straight away.
75
+
76
+ ## Change one customer's limit
77
+
78
+ From the customer's page in the dashboard, you can override a limit for that customer or reset their usage to 0. Plan limits don't change. See [Managing customer entitlements](/product-catalog/entitlements#managing-customer-entitlements).
@@ -4,7 +4,7 @@ slug: "promotions/create-a-promotion"
4
4
  section: "promotions"
5
5
  description: "Set up purchasing power parity discounts, country overrides, and security enforcement"
6
6
  ---
7
- A promotion ties a set of discounts to one or more of your products and plans. Once created, eligible visitors will see their local discount automatically.
7
+ A promotion ties a set of purchasing power parity (PPP) discounts to one or more of your products and plans. Once created, eligible visitors will see their local discount automatically.
8
8
 
9
9
 
10
10
 
@@ -24,7 +24,7 @@ A promotion ties a set of discounts to one or more of your products and plans. O
24
24
 
25
25
 
26
26
 
27
- Only **Published** plans appear in the selector. If a plan is missing, open the plan in **Product Catalog → Plans** and publish it first.
27
+ Only **Published** plans appear in the selector. If a plan is missing, open the product in **Product catalog → Products**, then publish the plan.
28
28
 
29
29
 
30
30
  At least one plan must be selected before you can create the promotion.
@@ -6,7 +6,7 @@ description: "Boost global sales with purchasing power parity and country-specif
6
6
  ---
7
7
  Promotions let you offer location-based discounts to customers around the world — automatically. Set up purchasing power parity (PPP) pricing, enforce security rules to prevent abuse, and render a customizable banner or discounted prices on your storefront — all from the Kelviq dashboard.
8
8
 
9
- Setup takes less than 5 minutes and works with your existing product catalog.
9
+ Promotions work with the products and plans you already have.
10
10
 
11
11
 
12
12
 
@@ -3,14 +3,20 @@ title: "Core concepts"
3
3
  slug: "quickstart/core-concepts"
4
4
  section: "quickstart"
5
5
  ---
6
- Understanding these core concepts will make it easier to design your pricing and integrate the SDK.
6
+ Kelviq has four building blocks: products, plans, features, and customers. This page uses one example throughout: **Acme AI**, a writing assistant with a Free and a Pro plan.
7
+
8
+ ```mermaid
9
+ flowchart LR
10
+ F["Features<br/>ai-credits · max-projects · priority-support"] --> P["Plan: Pro<br/>$29/month<br/>10,000 ai-credits/month"]
11
+ P --> C["Customer: cust_123<br/>subscribed to Pro"]
12
+ C --> B["Balance<br/>6,500 used · 3,500 remaining"]
13
+ ```
7
14
 
8
15
  ---
9
16
 
10
17
  ## Products
11
18
 
12
- A product is the main thing you sell.
13
- Examples: "Cursor", "TimeMaster Pro", or "API Service".
19
+ A product is the thing you sell. In the example, the product is **Acme AI**.
14
20
 
15
21
  [Learn more about products →](/product-catalog/products)
16
22
 
@@ -18,33 +24,34 @@ Examples: "Cursor", "TimeMaster Pro", or "API Service".
18
24
 
19
25
  ## Plans
20
26
 
21
- A plan is how you package and price your product. You attach features and prices to a plan.
27
+ A plan packages a product's price and features. Acme AI has two:
22
28
 
23
- Examples: Free, Starter, Pro, Enterprise.
29
+ | | Free | Pro |
30
+ | --- | --- | --- |
31
+ | Price | \$0 | \$29/month |
32
+ | `ai-credits` | 500/month | 10,000/month |
33
+ | `max-projects` | 3 | 50 |
34
+ | `priority-support` | Off | On |
24
35
 
25
36
  [Learn more about plans →](/product-catalog/plans)
26
37
 
27
38
  ---
28
39
 
29
- ## Features & Entitlements
30
-
31
- A feature is a capability a customer can access. Entitlements define how that feature gets used within a specific plan.
40
+ ## Features & limits
32
41
 
33
- You define features once and reuse them across multiple plans. Entitlements control the access, limits, or configuration for those features.
42
+ A feature is something a plan grants. You create a feature once and add it to as many plans as you like, each with its own value. In the API and SDKs, the value a plan gives a feature is called an entitlement.
34
43
 
35
- Examples:
36
- - API access with 1,000 requests per month
37
- - AI tokens with a limit of 10,000 tokens per month
38
- - Storage feature with 100 GB included
39
- - Priority support enabled for Pro customers
44
+ There are three feature types:
40
45
 
41
- Entitlements come in three types
46
+ | Type | What it does | In the example |
47
+ | --- | --- | --- |
48
+ | **Boolean** | Turns something on or off | `priority-support` |
49
+ | **Meter** | Counts usage against a limit that can reset | `ai-credits` |
50
+ | **Customizable** | Stores a number or setting for each plan | `max-projects` |
42
51
 
43
- * **Boolean** to toggle a feature on or off
44
- * **Metered** to track usage like AI tokens, workflow runs, or compute time
45
- * **Config** to pass custom values or settings to your application
52
+ Your app checks the feature, not the plan. Moving `priority-support` to the Free plan is a dashboard change, not a deploy.
46
53
 
47
- [Learn more about features & entitlements →](/product-catalog/entitlements)
54
+ [Learn more about features & limits →](/product-catalog/entitlements) · [How usage limits work →](/product-catalog/usage-limits)
48
55
 
49
56
  ---
50
57
 
@@ -80,25 +87,24 @@ Examples: Discord servers, Slack workspaces, Notion pages, member-only dashboard
80
87
 
81
88
  ## Customers
82
89
 
83
- A customer is a person or company that purchases your product.
90
+ A customer is a person or company that buys from you. Create a customer with your own ID, such as `cust_123`, when someone signs up in your app. When they buy Pro, Kelviq links the subscription to that customer and their `ai-credits` balance starts at 10,000.
84
91
 
85
- Typically, you create a customer record when someone signs up in your app.
86
- When they complete a purchase, Kelviq maps the transaction to the customer record automatically.
92
+ Each time they use a credit, your backend reports it. After 6,500 credits, Kelviq shows 3,500 remaining until the monthly reset.
87
93
 
88
- [Learn more about customers →](/coustomers-management/overview)
94
+ [Learn more about customers →](/customers-management/overview)
89
95
 
90
96
  ---
91
97
 
92
98
  ## Typical workflows
93
99
 
94
- ### AI and usage based products
100
+ ### AI and usage-based products
95
101
 
96
102
  Billing for actual work delivered rather than just seat access.
97
103
 
98
104
  1. Create features like AI tokens, API calls, or workflow runs
99
105
  2. Create a product
100
- 3. Create plans with a flat base fee plus metered usage charges
101
- 4. Add entitlements to set soft or hard caps on compute
106
+ 3. Create plans with a base fee plus usage charges
107
+ 4. Set usage limits on each plan, with a soft or hard limit
102
108
  5. Integrate the SDK to report usage back to Kelviq as the AI performs work
103
109
  6. Customer subscribes and pays automatically based on their actual consumption
104
110
 
@@ -119,7 +125,7 @@ Selling recurring access with feature limits:
119
125
  1. Create **features** (e.g., API calls, storage, AI tokens)
120
126
  2. Create a **product**
121
127
  3. Create **plans** with recurring pricing (monthly/yearly)
122
- 4. Add **entitlements** to each plan (e.g., 1,000 API calls/month)
128
+ 4. Add **features & limits** to each plan (e.g., 1,000 API calls/month)
123
129
  5. Integrate the **SDK** to check feature access and enforce limits
124
130
  6. Customer subscribes → SDK controls what they can access
125
131
 
@@ -129,10 +135,10 @@ Selling recurring access with feature limits:
129
135
 
130
136
  To bring everything you set up in the dashboard into your app, use one of these options:
131
137
 
132
- - **[SDKs](/frontend-integration/react-sdk)** — check feature access and enforce usage limits in code
138
+ - **SDKs** ([Node](/backend-integration/node-sdk), [Python](/backend-integration/python-sdk), [React](/frontend-integration/react-sdk), [JavaScript](/frontend-integration/js-sdk)) — check feature access and enforce usage limits in code
133
139
  - **[APIs](/api-reference/authentication)** — use for custom needs such as syncing usage or triggering upgrades
134
140
 
135
- **No webhooks required.** Kelviq SDKs and UI widgets stay in sync automatically—no need to build webhook handlers or manage event processing.
141
+ **Webhooks are optional.** The SDKs and UI widgets read access from Kelviq directly. Use [webhooks](/guides/webhooks) when you want events in your own systems.
136
142
 
137
143
  [See the full integration guide →](/quickstart/integrate-with-your-app)
138
144
 
@@ -141,6 +147,6 @@ To bring everything you set up in the dashboard into your app, use one of these
141
147
  ## Need help?
142
148
 
143
149
  Have questions, need help with implementation, or want a walkthrough?
144
- Email us at **hi@kelviq.com** or [book a demo](https://tidycal.com/neravath/15-minute-meeting).
150
+ Email us at **hi@kelviq.com** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
145
151
 
146
152
  ---