@kelviq/mcp-server 0.4.0 → 1.1.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 (76) hide show
  1. package/README.md +43 -27
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/README.md +16 -0
  6. package/dist/docs/backend-integration/better-auth.md +369 -0
  7. package/dist/docs/backend-integration/node-sdk.md +373 -5
  8. package/dist/docs/backend-integration/python-sdk.md +444 -6
  9. package/dist/docs/changelog/api.md +516 -5
  10. package/dist/docs/changelog/app.md +162 -0
  11. package/dist/docs/changelog/cli.md +33 -0
  12. package/dist/docs/changelog/mcp-server.md +23 -0
  13. package/dist/docs/changelog/node-sdk.md +124 -0
  14. package/dist/docs/changelog/python-sdk.md +135 -0
  15. package/dist/docs/changelog.md +3968 -0
  16. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  17. package/dist/docs/checkout/checkout-configuration.md +88 -22
  18. package/dist/docs/checkout/checkout-metadata.md +219 -0
  19. package/dist/docs/checkout/static-checkout-url.md +201 -0
  20. package/dist/docs/cli/commands.md +1 -1
  21. package/dist/docs/cli/environments.md +17 -9
  22. package/dist/docs/cli/kelviq-config.md +35 -1
  23. package/dist/docs/cli/overview.md +2 -0
  24. package/dist/docs/coustomers-management/overview.md +15 -19
  25. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  26. package/dist/docs/frontend-integration/react-ui.md +51 -16
  27. package/dist/docs/getstarted/fees.md +45 -54
  28. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  29. package/dist/docs/getstarted/review-process.md +3 -3
  30. package/dist/docs/guides/agent-toolkit.md +143 -0
  31. package/dist/docs/guides/mcp-server.md +138 -35
  32. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  33. package/dist/docs/guides/sandbox.md +34 -0
  34. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  35. package/dist/docs/guides/subscription-integration.md +28 -4
  36. package/dist/docs/guides/webhooks.md +367 -6
  37. package/dist/docs/manifest.json +98 -56
  38. package/dist/docs/openapi.json +7411 -2648
  39. package/dist/docs/payouts/overview.md +30 -0
  40. package/dist/docs/payouts/transactions.md +50 -6
  41. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  42. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  43. package/dist/docs/product-catalog/discounts.md +25 -12
  44. package/dist/docs/product-catalog/entitlements.md +53 -16
  45. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  46. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  47. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  48. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  49. package/dist/docs/product-catalog/plans.md +14 -0
  50. package/dist/docs/product-catalog/products.md +5 -13
  51. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  52. package/dist/docs/product-catalog/subscriptions.md +109 -12
  53. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  54. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  55. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  56. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  57. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  58. package/dist/http/client.js +9 -2
  59. package/dist/http/client.js.map +1 -1
  60. package/dist/http/errors.d.ts +8 -0
  61. package/dist/http/errors.js +20 -0
  62. package/dist/http/errors.js.map +1 -1
  63. package/dist/schemas/kelviq.d.ts +199 -0
  64. package/dist/schemas/kelviq.js +173 -0
  65. package/dist/schemas/kelviq.js.map +1 -1
  66. package/dist/server.js +11 -1
  67. package/dist/server.js.map +1 -1
  68. package/dist/tools/discounts.d.ts +3 -0
  69. package/dist/tools/discounts.js +74 -0
  70. package/dist/tools/discounts.js.map +1 -0
  71. package/dist/tools/index.js +4 -0
  72. package/dist/tools/index.js.map +1 -1
  73. package/dist/tools/webhooks.d.ts +10 -0
  74. package/dist/tools/webhooks.js +114 -0
  75. package/dist/tools/webhooks.js.map +1 -0
  76. package/package.json +1 -1
@@ -0,0 +1,257 @@
1
+ ---
2
+ title: "Usage alerts"
3
+ slug: "product-catalog/usage-alerts"
4
+ section: "product-catalog"
5
+ description: "Configure usage thresholds and receive feature.usage_alert webhooks"
6
+ ---
7
+ Usage alerts tell your application when a customer's metered feature crosses a threshold. Use them with any meter feature, such as API calls, credits, tokens, or storage.
8
+
9
+ A usage alert has two parts. You configure the threshold on the plan, then receive the `feature.usage_alert` event through a webhook. Turning on the alert does not email the customer or show an in-app message by itself. Your webhook handler decides what happens next.
10
+
11
+ ## How usage alerts work
12
+
13
+ 1. Your application reports usage to Kelviq with `SET` or `DELTA` behavior.
14
+ 2. Kelviq updates the customer's meter for the current usage period.
15
+ 3. When current usage crosses a configured threshold, Kelviq creates a `feature.usage_alert` event.
16
+ 4. Kelviq sends the event to webhook endpoints subscribed to that event type.
17
+ 5. Your application can send an email, show an in-app warning, notify a support team, or offer an upgrade.
18
+
19
+ Usage alerts do not stop usage, change a price, or charge the customer. Use a hard limit to stop usage at zero balance, and configure usage pricing when customers should pay for additional consumption.
20
+
21
+ ## Choose a threshold type
22
+
23
+ Kelviq supports percentage and absolute-unit thresholds.
24
+
25
+ | Dashboard option | API value | When it triggers | Valid values |
26
+ | --- | --- | --- | --- |
27
+ | Percentage | `PERCENTAGE` | Current usage reaches a percentage of the feature's usage limit | 1–100 |
28
+ | Balance | `BALANCE` | Current usage reaches an absolute number of feature units | Any number greater than or equal to 1 |
29
+
30
+ Suppose a plan includes 10,000 API calls each month:
31
+
32
+ - A 75% percentage threshold is crossed when current usage reaches 7,500 calls.
33
+ - A balance threshold of 7,500 is crossed at the same usage count, but it is stored as an absolute number of calls rather than a percentage.
34
+
35
+ Percentage thresholds are easier to reuse across plans with different limits. Balance thresholds are useful when the absolute number matters, such as 10,000 API calls or 1,000 AI credits.
36
+
37
+ You can add more than one threshold. For example, use 75% for an early warning and 90% for a stronger upgrade or top-up prompt.
38
+
39
+ ## Configure usage alerts in the dashboard
40
+
41
+ 1. Open **Product Catalog → Products** and select the product.
42
+ 2. Open the plan that contains the metered feature.
43
+ 3. Edit **Usage pricing** or open **Manage features & limits**.
44
+ 4. Select the meter feature and enter its usage value or pricing configuration.
45
+ 5. Turn on **Usage alert**.
46
+ 6. Choose **Percentage** or **Balance** as the threshold type.
47
+ 7. Click **Add threshold** and enter each threshold.
48
+ 8. Save the configuration. If Kelviq creates a draft version of a published plan, publish the draft before testing it.
49
+
50
+ <img height="400" src="/images/usage-alerts.png" />
51
+
52
+ If the Usage alert switch is disabled while managing an entitlement, make sure you selected a meter feature and entered a value. Percentage alerts also need a finite usage limit so Kelviq can calculate the percentage used.
53
+
54
+ Regional prices inherit usage alerts from the base price. Change the base price when the same alert configuration should apply to every regional price.
55
+
56
+ ## Configure usage alerts through the API
57
+
58
+ To update one plan entitlement, send a `PATCH` request to:
59
+
60
+ ```text
61
+ /api/v1/catalog/plans/{plan_identifier}/features/{feature_identifier}/
62
+ ```
63
+
64
+ `feature_identifier` is the feature's identifier, such as `api-calls`, not its UUID.
65
+
66
+ ```bash
67
+ curl --request PATCH \
68
+ --url https://api.kelviq.com/api/v1/catalog/plans/pro/features/api-calls/ \
69
+ --header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
70
+ --header "Content-Type: application/json" \
71
+ --data '{
72
+ "details": {
73
+ "value": 10000,
74
+ "hasUnlimitedUsage": false,
75
+ "reset": "EVERY_MONTH",
76
+ "resetTime": "BEGINNING_OF_PERIOD",
77
+ "usageAlerts": {
78
+ "enabled": true,
79
+ "thresholds": [75, 90],
80
+ "thresholdType": "PERCENTAGE"
81
+ },
82
+ "hardLimit": false
83
+ }
84
+ }'
85
+ ```
86
+
87
+ The `usageAlerts` object contains:
88
+
89
+ | Field | Type | Description |
90
+ | --- | --- | --- |
91
+ | `enabled` | boolean | Turns alerts on or off for the entitlement |
92
+ | `thresholds` | number[] | Percentage or unit values to watch |
93
+ | `thresholdType` | string | `PERCENTAGE` or `BALANCE` |
94
+
95
+ Updating a published plan creates a new draft version. Publish that draft before expecting the new thresholds to apply. See [Update plan entitlement](/api-reference/plan-entitlements/update-plan-entitlement) for the complete request schema.
96
+
97
+ ## Create the webhook endpoint
98
+
99
+ The threshold configuration tells Kelviq when to create an alert. The webhook endpoint is how your application receives it.
100
+
101
+ 1. Open **Settings → Webhooks** in the Kelviq dashboard.
102
+ 2. Create an endpoint with a public HTTPS URL.
103
+ 3. Subscribe the endpoint to `feature.usage_alert`.
104
+ 4. Save the signing secret. Kelviq shows it once.
105
+ 5. Verify every delivery before reading its data.
106
+
107
+ The webhook endpoint and usage reports must use the same environment. A production webhook does not receive alerts created from sandbox usage, and a sandbox webhook does not receive production alerts.
108
+
109
+ See the [Webhooks guide](/guides/webhooks) for signature verification, retries, delivery logs, and manual resends.
110
+
111
+ ## Usage alert payload
112
+
113
+ The event identifies the customer, feature, usage limit, current usage, threshold, subscription, and usage period.
114
+
115
+ ```json
116
+ {
117
+ "id": "575a1aa4-3414-4e08-b4ad-6bfd3e96322d",
118
+ "type": "feature.usage_alert",
119
+ "created_at": "2026-05-18T18:48:59Z",
120
+ "data": {
121
+ "object": {
122
+ "id": "a1c88c9d-19cf-48cc-b194-6cc6ebb356ee",
123
+ "object": "feature_usage_alert",
124
+ "feature": {
125
+ "id": "245d745f-28ca-4856-81fe-1e1f5c6c7ebd",
126
+ "name": "API calls",
127
+ "identifier": "api-calls",
128
+ "feature_type": "METER"
129
+ },
130
+ "customer": {
131
+ "id": "d2b6c9ac-bcd5-4e59-8c7e-b6472485e112",
132
+ "name": "Geo",
133
+ "email": "geo@example.com",
134
+ "customer_id": "customer-123"
135
+ },
136
+ "usage_limit": 10000,
137
+ "current_usage": 9000,
138
+ "threshold_type": "PERCENTAGE",
139
+ "threshold_value": 90,
140
+ "period_start_time": "2026-05-01T00:00:00Z",
141
+ "period_end_time": "2026-06-01T00:00:00Z",
142
+ "subscription_id": "137e4652-5540-4a3b-9bce-fa393b028539",
143
+ "organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c"
144
+ }
145
+ }
146
+ }
147
+ ```
148
+
149
+ The fields most alert handlers use are:
150
+
151
+ | Field | Use |
152
+ | --- | --- |
153
+ | Top-level `id` | Idempotency key for deduplicating webhook deliveries |
154
+ | `feature.identifier` | Maps the alert to a feature in your application |
155
+ | `customer.customer_id` | Maps the alert to your own user or account |
156
+ | `customer.email` | Address for a customer notification, if you choose to send one |
157
+ | `usage_limit` | Configured usage allowance |
158
+ | `current_usage` | Usage recorded when the event was created |
159
+ | `threshold_type` | Whether `threshold_value` is a percentage or absolute unit count |
160
+ | `threshold_value` | The configured threshold that was crossed |
161
+ | `period_start_time`, `period_end_time` | Usage period associated with the alert |
162
+ | `subscription_id` | Subscription that owns the entitlement |
163
+
164
+ ## Handle `feature.usage_alert`
165
+
166
+ This Express example verifies the request and sends the alert to an application queue. The queue can handle email or in-app notifications outside the webhook request.
167
+
168
+ ```typescript
169
+ import express from "express";
170
+ import {
171
+ validateEvent,
172
+ WebhookVerificationError,
173
+ } from "@kelviq/node-sdk";
174
+
175
+ const app = express();
176
+
177
+ app.post(
178
+ "/webhooks/kelviq",
179
+ express.raw({ type: "application/json" }),
180
+ async (req, res) => {
181
+ try {
182
+ const event = validateEvent(
183
+ req.body,
184
+ req.headers,
185
+ process.env.KELVIQ_WEBHOOK_SECRET!,
186
+ );
187
+
188
+ if (event.type === "feature.usage_alert") {
189
+ const alert = event.data.object;
190
+
191
+ // `notificationQueue` is your own queue or background-job service.
192
+ await notificationQueue.add("usage-alert", {
193
+ eventId: event.id,
194
+ customerId: alert.customer.customer_id,
195
+ email: alert.customer.email,
196
+ featureId: alert.feature.identifier,
197
+ currentUsage: alert.current_usage,
198
+ usageLimit: alert.usage_limit,
199
+ thresholdType: alert.threshold_type,
200
+ thresholdValue: alert.threshold_value,
201
+ });
202
+ }
203
+
204
+ return res.sendStatus(202);
205
+ } catch (error) {
206
+ if (error instanceof WebhookVerificationError) {
207
+ return res.sendStatus(403);
208
+ }
209
+
210
+ return res.sendStatus(500);
211
+ }
212
+ },
213
+ );
214
+ ```
215
+
216
+ Kelviq may deliver the same event more than once because of automatic retries or a manual resend. Store the top-level event `id` or `webhook-id` header before enqueueing work, and skip the event if you already processed it.
217
+
218
+ Return a `2xx` response quickly. Do not wait for an email provider or another slow service inside the webhook request.
219
+
220
+ ## Test an alert in sandbox
221
+
222
+ 1. Create a sandbox webhook endpoint subscribed to `feature.usage_alert`.
223
+ 2. Configure a low threshold on a sandbox plan, such as 1 unit or 1%.
224
+ 3. Report enough usage to cross the threshold.
225
+ 4. Open **Settings → Webhooks**, select the endpoint, and inspect the delivery log.
226
+ 5. Confirm the event's customer, feature, threshold, and usage period.
227
+
228
+ For example, report a usage increment with the Node SDK:
229
+
230
+ ```typescript
231
+ import { BEHAVIOUR_CHOICES, Kelviq } from "@kelviq/node-sdk";
232
+
233
+ const kelviq = new Kelviq({
234
+ accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY!,
235
+ environment: "sandbox",
236
+ });
237
+
238
+ await kelviq.reporting.reportUsage({
239
+ customerId: "customer-123",
240
+ featureId: "api-calls",
241
+ value: 2,
242
+ behaviour: BEHAVIOUR_CHOICES.DELTA,
243
+ });
244
+ ```
245
+
246
+ If delivery fails, fix the endpoint and use **Resend** from the delivery log. Keep the handler idempotent because a resend can deliver the same event again.
247
+
248
+ ## Troubleshooting
249
+
250
+ | Problem | What to check |
251
+ | --- | --- |
252
+ | The Usage alert switch is disabled | Confirm that the feature is a meter and has a configured value |
253
+ | No webhook arrives | Confirm the endpoint subscribes to `feature.usage_alert`, the plan version is published, and usage crossed a configured threshold |
254
+ | Sandbox testing produces no production delivery | Make sure usage reports, plan configuration, API key, and webhook all belong to the same environment |
255
+ | Percentage threshold does not match expectations | Compare `current_usage` with `usage_limit`; percentage thresholds measure usage against that limit |
256
+ | The handler runs twice | Deduplicate using the event `id` or `webhook-id`; retries and manual resends can duplicate a delivery |
257
+ | Customers receive no email | Kelviq emits the webhook event; your application must send the email or in-app notification |
@@ -8,13 +8,13 @@ AI products perform actual work. Flat rate subscriptions force you to guess at a
8
8
 
9
9
  ## Set up a usage plan
10
10
 
11
- To add consumption tracking to a plan open your pricing configuration and expand the usage pricing card.
11
+ To add consumption tracking to a plan, open its pricing configuration and expand **Usage charges**.
12
12
 
13
13
  <img height="200" src="/images/usage-pricing-card.png" />
14
14
 
15
15
  ### 1. Select or create a metered feature
16
16
 
17
- Choose the specific metric you want to track from the dropdown list. You can select an existing feature like Platform API or Tokens consumed. To create a new metered feature just type a name like API request and hit enter.
17
+ 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
18
 
19
19
  <img height="200" src="/images/select-metered-feature.png" />
20
20
 
@@ -28,9 +28,9 @@ Select how payments are structured.
28
28
  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
29
 
30
30
  **Pay as you go**
31
- Customers pay in arrears based on exactly what they consumed. AI agents run autonomously and their usage fluctuates wildly. A user might trigger a research workflow that consumes massive amounts of compute overnight. Pay as you go ensures the agent keeps working without interruption while you capture the exact margin for the underlying infrastructure costs. We tally the final unit count at the end of the billing period and charge the card.
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.
32
32
 
33
- The pay as you go model only works on monthly plans.
33
+ Monthly must be the plan's only billing period. Pay as you go does not support Stair-step pricing or credit rollover.
34
34
 
35
35
  ### 3. Configure the pricing model
36
36
 
@@ -169,30 +169,67 @@ If you select Tiered you specify the first unit and last unit for each bucket. Y
169
169
 
170
170
  You can also set localized pricing for usage based billing. This lets you define different per unit rates for specific countries and currencies.
171
171
 
172
+ #### Regional pricing and usage controls
173
+
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.
175
+
176
+ Update these controls on the base price when you want the same behavior across its regional prices.
177
+
172
178
  ### 5. Set the usage reset cadence
173
179
 
174
- Configure how often the usage meter clears out.
180
+ Configure how often the usage meter resets. Credit rollover is calculated when this reset happens.
175
181
 
176
- You can set the reset to Never for lifetime limits. You can also choose to reset it Every week or Every month.
182
+ Use **Never** for a lifetime limit, or choose a recurring reset such as every week or every month. A meter set to **Never** has no period boundary at which to roll unused credits forward.
177
183
 
178
- For monthly resets you can align the timing perfectly by setting it to the first day of each month or tying it directly to the subscription start date.
184
+ For monthly resets, choose either the first day of the month or the customer's subscription start date.
179
185
 
180
186
  ### 6. Configure rollover and alerts
181
187
 
182
- If your customers buy usage upfront you can let them keep what they do not use. Toggle Credit rollover to define how much carries over to the next billing cycle. You can set a specific percentage of unused units to roll over and apply a hard limit on the total units.
188
+ #### Credit rollover
189
+
190
+ Credit rollover lets a customer keep part of an advance commitment they did not use before the meter resets. It is available for **Advance commitment** usage prices, not **Pay as you go** prices.
191
+
192
+ To configure it:
193
+
194
+ 1. In the plan editor, expand **Usage charges** and open the metered feature.
195
+ 2. Choose **Advance commitment** as the billing model.
196
+ 3. Set the included **Value** and a recurring **Usage reset**.
197
+ 4. Turn on **Credit rollover**.
198
+ 5. Enter the **Percentage** of unused units to carry forward. The value can be from 0% to 100%.
199
+ 6. Enter a **Limit** in units to cap the rollover amount.
183
200
 
184
201
  <img height="400" src="/images/credits-rollover.png" />
185
202
 
186
- Keep your users informed as they consume their quota. Toggle Usage alerts and set your threshold type.
203
+ 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.
187
204
 
188
- <img height="200" src="/images/usage-alerts.png" />
205
+ The rollover limit and the usage hard limit do different jobs. The rollover limit caps the credits carried into a new period. The hard limit stops additional usage when the customer's balance reaches zero.
189
206
 
190
- You can click Add threshold to stack multiple percentage alerts. For example you can notify them at 75 percent and again at 90 percent so they are never surprised by a cutoff or an unexpected bill.
207
+ #### Usage alerts
191
208
 
192
- To receive these alerts you must create a webhook for the feature.usage_alert event.
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.
210
+
211
+ See [Usage alerts](/product-catalog/usage-alerts) for dashboard and API configuration, the webhook payload, a Node.js handler, and sandbox testing steps.
193
212
 
194
213
  ### 7. Stack multiple usage metrics
195
214
 
196
215
  <img height="400" src="/images/stack-multiple-usage-metrics.png" />
197
216
 
198
217
  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
+
219
+ ## Model a plan with different kinds of limits
220
+
221
+ 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.
222
+
223
+ | Plan capability | Feature type | Suggested configuration |
224
+ | --- | --- | --- |
225
+ | Messages | Meter | Reset every month |
226
+ | Training runs | Meter | Reset every day |
227
+ | Active agents | Customizable | Store the plan's allowed count |
228
+ | Knowledge sources | Customizable | Store the plan's allowed count |
229
+ | WhatsApp access | Boolean | Enable on the plans that include it |
230
+ | Analytics | Boolean | Enable on the plans that include it |
231
+ | Priority support | Boolean | Enable on the plans that include it |
232
+
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.
234
+
235
+ 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.
@@ -30,7 +30,7 @@ From the product page:
30
30
 
31
31
  From the plan page, click the **Price** section to configure pricing:
32
32
 
33
- 1. Select billing cycles: **Monthly**, **Yearly**, **3 Months**, or **One Time**
33
+ 1. Select billing cycles: **28 Days** (when enabled), **Monthly**, **Yearly**, **3 Months**, or **One Time**
34
34
  2. Enter prices for each selected billing cycle
35
35
  3. (Optional) Enable **Free trial** and set the trial period in days
36
36
  4. Click **Save**
@@ -0,0 +1,64 @@
1
+ ---
2
+ title: "Abandoned cart recovery"
3
+ slug: "sales/abandoned-cart-recovery"
4
+ section: "sales"
5
+ description: "Automatically remind customers who start checkout but do not pay"
6
+ ---
7
+ Abandoned cart recovery emails customers who start a checkout but do not complete payment. Kelviq detects the abandoned checkout, sends up to three reminder emails over three days, and expires the checkout after four. You do not need to build anything: detection, scheduling, and deduplication are handled for you.
8
+
9
+ The feature is on by default for every organization. You can turn it off in **Settings**.
10
+
11
+ ## How a checkout becomes abandoned
12
+
13
+ Kelviq marks a checkout as abandoned when all of the following are true:
14
+
15
+ * The checkout was created at least one hour ago.
16
+ * Its status is `open` or `processing`.
17
+ * The customer has not touched it in the last 30 minutes.
18
+
19
+ Recent customer activity delays the marking, so a customer who is still filling in payment details is not emailed.
20
+
21
+ A reminder also needs somewhere to go: the customer must have an email address, taken from the linked customer record or the email entered during checkout.
22
+
23
+ ## Reminder schedule
24
+
25
+ All timings are measured from when the checkout session was created.
26
+
27
+ | Event | When |
28
+ | --- | --- |
29
+ | Checkout marked as abandoned | After 1 hour |
30
+ | First reminder email | After 24 hours |
31
+ | Second reminder email | After 48 hours |
32
+ | Final reminder email | After 72 hours |
33
+ | Checkout expires | After 4 days |
34
+
35
+ The background jobs that send these run hourly, so an email can arrive up to an hour after its nominal time.
36
+
37
+ The reminders are sequential. The second email is only sent after the first, and the third only after the second. Each email includes a **Return to checkout** link that takes the customer back to their session, and each send is recorded so a customer is never emailed twice for the same step.
38
+
39
+ The subject lines are:
40
+
41
+ 1. `You left {productName} in checkout`
42
+ 2. `Still interested in {productName}?`
43
+ 3. `Last reminder about your {productName} checkout`
44
+
45
+ ## What happens at expiration
46
+
47
+ Four days after creation, an unpaid checkout expires:
48
+
49
+ * The checkout status becomes `expired` and its payment status becomes `canceled`.
50
+ * The recovery link in earlier emails stops working.
51
+ * No further reminders are sent.
52
+
53
+ Completed, closed, or expired checkouts never receive reminders.
54
+
55
+ ## Turning it off and on
56
+
57
+ Use the **Abandoned cart recovery** toggle in **Settings &rarr; Notifications** to control the feature for your whole organization.
58
+
59
+ * Turning it off stops future reminder emails. Emails that were already sent cannot be recalled.
60
+ * Turning it back on resumes eligible reminders for checkouts that have not yet expired.
61
+
62
+ The reminder timing and email content are fixed. There is currently no option to change the schedule, resend a reminder manually, or exclude individual checkouts.
63
+
64
+ To watch recovery in action, open [Checkout sessions](/sales/checkout-sessions). An abandoned checkout stays in its `open` or `processing` state until the customer returns and pays or the session expires.
@@ -0,0 +1,144 @@
1
+ ---
2
+ title: "Create a one-time charge"
3
+ slug: "sales/create-a-one-time-charge"
4
+ section: "sales"
5
+ description: "Charge a customer's saved payment method without sending them through checkout"
6
+ ---
7
+ Use the Create Charge API when an existing customer has agreed to a one-time purchase and already has a usable payment method saved in Kelviq. The payment is attempted immediately, so the customer does not need to complete another checkout session.
8
+
9
+ Common examples include selling an add-on after the original checkout or collecting a one-time setup fee from an existing customer.
10
+
11
+ Create a charge from your backend only. It requires a Server API Key, which must never be exposed in browser or mobile-app code.
12
+
13
+ ## Before you start
14
+
15
+ Make sure all of the following are true:
16
+
17
+ - The customer already exists in the same Kelviq environment as your API key.
18
+ - The customer has a usable default payment method from a previous checkout or an active subscription.
19
+ - The plan has a one-time price and you know its plan identifier.
20
+ - You have the customer's unique `customerId`.
21
+
22
+ Sandbox and production are isolated. A sandbox customer or payment method cannot be charged with a production key, and the reverse is also true.
23
+
24
+ ## Create the charge
25
+
26
+ Send `POST /api/v1/charges/` with the plan and customer identifiers. `chargePeriod` must be `ONE_TIME`.
27
+
28
+ ```bash cURL
29
+ curl --request POST \
30
+ --url https://sandboxapi.kelviq.com/api/v1/charges/ \
31
+ --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
32
+ --header "Content-Type: application/json" \
33
+ --data '{
34
+ "planIdentifier": "lifetime-access",
35
+ "chargePeriod": "ONE_TIME",
36
+ "customerId": "cust_789",
37
+ "currencyCode": "USD",
38
+ "features": [
39
+ {
40
+ "identifier": "seats",
41
+ "quantity": 5
42
+ }
43
+ ]
44
+ }'
45
+ ```
46
+
47
+ ```typescript Node.js SDK
48
+ import { Kelviq } from "@kelviq/node-sdk";
49
+
50
+ const client = new Kelviq({
51
+ accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
52
+ environment: "sandbox",
53
+ });
54
+
55
+ const charge = await client.charges.create({
56
+ planIdentifier: "lifetime-access",
57
+ chargePeriod: "ONE_TIME",
58
+ customerId: "cust_789",
59
+ currencyCode: "USD",
60
+ features: [{ identifier: "seats", quantity: 5 }],
61
+ });
62
+
63
+ console.log(charge.id, charge.status, charge.amount);
64
+ ```
65
+
66
+ ```python Python SDK
67
+ import os
68
+ from kelviq_sdk import Kelviq
69
+
70
+ client = Kelviq.create_sync_client(
71
+ access_token=os.environ["KELVIQ_SANDBOX_SERVER_API_KEY"],
72
+ environment="sandbox",
73
+ )
74
+
75
+ charge = client.charges.create(
76
+ planIdentifier="lifetime-access",
77
+ chargePeriod="ONE_TIME",
78
+ customerId="cust_789",
79
+ currencyCode="USD",
80
+ features=[{"identifier": "seats", "quantity": 5}],
81
+ )
82
+
83
+ print(charge.id, charge.status, charge.amount)
84
+ ```
85
+
86
+ The `features` and `currencyCode` fields are optional. Include `features` when the customer is choosing a quantity, such as five seats. If the customer already has a currency, `currencyCode` must match it.
87
+
88
+ ## Handle the response
89
+
90
+ A successful request returns `201 Created` with the charge record:
91
+
92
+ ```json
93
+ {
94
+ "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
95
+ "startDate": "2026-06-20",
96
+ "endDate": null,
97
+ "billingPeriodStartTime": null,
98
+ "billingPeriodEndTime": null,
99
+ "amount": "49.00",
100
+ "recurrence": "",
101
+ "currency": "USD",
102
+ "status": "active",
103
+ "product": {
104
+ "name": "Invoice Test",
105
+ "id": "88e437b8-6017-405b-9328-e0f4e140bb79",
106
+ "identifier": "invoice-test"
107
+ },
108
+ "plan": {
109
+ "name": "Lifetime Access",
110
+ "identifier": "lifetime-access"
111
+ },
112
+ "features": [],
113
+ "trialDaysRemaining": 0,
114
+ "customerId": "cust_789",
115
+ "billingType": "ONE_TIME"
116
+ }
117
+ ```
118
+
119
+ Store the returned `id` with your own purchase record. You can also confirm the payment from **Sales → Orders** in the Kelviq dashboard.
120
+
121
+ ## Handle failed charges
122
+
123
+ The API returns `400 Bad Request` when Kelviq cannot complete the payment. The response includes a `detail` message describing the problem.
124
+
125
+ | Cause | What to do |
126
+ | --- | --- |
127
+ | No default payment method | Send the customer through checkout so they can add a payment method. |
128
+ | Payment declined | Ask the customer to update their payment method, then try again with their approval. |
129
+ | Payment requires authentication | Use checkout so the customer can complete the required authentication. |
130
+ | `chargePeriod` is not `ONE_TIME` | Use `ONE_TIME`, or use the Subscriptions API for recurring billing. |
131
+ | API key and customer are in different environments | Use the matching sandbox or production key and customer. |
132
+
133
+ Do not automatically retry a `400` response. If a request times out and the outcome is unclear, check **Sales → Orders** before sending it again to avoid charging the customer twice.
134
+
135
+ ## When to use checkout instead
136
+
137
+ Use a [checkout session](/checkout/checkout-configuration) when the customer needs to:
138
+
139
+ - enter a payment method for the first time;
140
+ - complete card or bank authentication;
141
+ - review and confirm the purchase in a hosted payment flow; or
142
+ - start a recurring subscription.
143
+
144
+ For every request field and response property, see [Create a charge API reference](/api-reference/charges/create-a-charge).
@@ -1,5 +1,5 @@
1
1
  import { requireKey, MissingKeyError } from '../config.js';
2
- import { fromException, fromHttpResponse } from './errors.js';
2
+ import { authHint, fromException, fromHttpResponse } from './errors.js';
3
3
  export class KelviqHttpClient {
4
4
  config;
5
5
  constructor(config) {
@@ -45,7 +45,14 @@ export class KelviqHttpClient {
45
45
  }
46
46
  }
47
47
  if (!response.ok) {
48
- return { ok: false, ...fromHttpResponse(response.status, parsed) };
48
+ const failure = fromHttpResponse(response.status, parsed);
49
+ const hint = authHint(response.status, this.config.env, this.config.envExplicit ?? true, init.auth === 'server' ? 'KELVIQ_SERVER_API_KEY' : 'KELVIQ_CLIENT_API_KEY');
50
+ if (hint) {
51
+ // The API's own detail often has no trailing punctuation ("Invalid Bearer Token").
52
+ const separator = /[.!?]$/.test(failure.error.message) ? ' ' : '. ';
53
+ failure.error.message = `${failure.error.message}${separator}${hint}`;
54
+ }
55
+ return { ok: false, ...failure };
49
56
  }
50
57
  return { ok: true, data: parsed };
51
58
  }
@@ -1 +1 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"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"}
@@ -17,4 +17,12 @@ export interface KelviqAPIError {
17
17
  }
18
18
  export declare function isKelviqAPIError(value: unknown): value is KelviqAPIError;
19
19
  export declare function fromHttpResponse(httpStatus: number, body: unknown): KelviqAPIError;
20
+ /**
21
+ * A 401/403 almost always means the key belongs to the other environment
22
+ * (key↔host binding is enforced server-side). Since 1.0.0 an unset
23
+ * KELVIQ_ENV means sandbox — before that it meant production — so upgraded
24
+ * configs holding a production key land here. Returns the sentence to append
25
+ * to the error message, or undefined for non-auth statuses.
26
+ */
27
+ export declare function authHint(httpStatus: number, env: 'production' | 'sandbox', envExplicit: boolean, keyVar: string): string | undefined;
20
28
  export declare function fromException(err: unknown): KelviqAPIError;