@kelviq/mcp-server 0.3.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -30
- package/dist/config.d.ts +5 -0
- package/dist/config.js +31 -10
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +84 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +134 -63
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +109 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -0
- package/dist/schemas/kelviq.js +50 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +15 -3
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +3 -0
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +8 -0
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.js +1 -0
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +5 -0
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +5 -1
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- 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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
180
|
+
Configure how often the usage meter resets. Credit rollover is calculated when this reset happens.
|
|
175
181
|
|
|
176
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
207
|
+
#### Usage alerts
|
|
191
208
|
|
|
192
|
-
|
|
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 → 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).
|
package/dist/http/client.js
CHANGED
|
@@ -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
|
-
|
|
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
|
}
|
package/dist/http/client.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9F,OAAO,EAAuB,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"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"}
|
package/dist/http/errors.d.ts
CHANGED
|
@@ -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;
|