@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.
- package/README.md +43 -27
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/README.md +16 -0
- 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 +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/changelog.md +3968 -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 +138 -35
- 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 +98 -56
- 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/schemas/kelviq.d.ts +199 -0
- package/dist/schemas/kelviq.js +173 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +11 -1
- package/dist/server.js.map +1 -1
- package/dist/tools/discounts.d.ts +3 -0
- package/dist/tools/discounts.js +74 -0
- package/dist/tools/discounts.js.map +1 -0
- package/dist/tools/index.js +4 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/webhooks.d.ts +10 -0
- package/dist/tools/webhooks.js +114 -0
- package/dist/tools/webhooks.js.map +1 -0
- package/package.json +1 -1
|
@@ -0,0 +1,3968 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Changelog"
|
|
3
|
+
slug: "changelog"
|
|
4
|
+
section: "root"
|
|
5
|
+
description: "Every Kelviq release across the dashboard, API, SDKs, and developer tools"
|
|
6
|
+
---
|
|
7
|
+
import { ChangelogFilter } from "/snippets/changelog-filter.jsx";
|
|
8
|
+
|
|
9
|
+
<Update label="v1.1.0" description="September 16, 2026" tags={["MCP Server"]}>
|
|
10
|
+
|
|
11
|
+
### New Features
|
|
12
|
+
|
|
13
|
+
#### Discount and webhook tools
|
|
14
|
+
|
|
15
|
+
11 new tools bring the server to 56:
|
|
16
|
+
|
|
17
|
+
- Discounts: `discount_list`, `discount_create`, `discount_retrieve`, `discount_update` to enable or disable a code, and `discount_archive`
|
|
18
|
+
- Webhooks: `webhook_endpoint_list`, `webhook_endpoint_create`, `webhook_endpoint_retrieve`, `webhook_endpoint_update`, `webhook_endpoint_delete`, and `webhook_log_list` for delivery attempts from the last 30 days
|
|
19
|
+
|
|
20
|
+
Webhook signing secrets are hidden in tool results so they don't end up in your AI conversation. Pass `revealSecret: true` when you need the value.
|
|
21
|
+
|
|
22
|
+
### Improvements
|
|
23
|
+
|
|
24
|
+
- `checkout_create_session` accepts `trialPeriod`, `billingPeriodsEnabled` and `email`.
|
|
25
|
+
- `subscription_update` accepts `prorationBehavior`, and `subscription_cancel` accepts `cancellationFeedback` and `cancellationComment`.
|
|
26
|
+
|
|
27
|
+
</Update>
|
|
28
|
+
|
|
29
|
+
<Update label="v0.3.0" description="September 15, 2026" tags={["CLI"]}>
|
|
30
|
+
|
|
31
|
+
### Breaking Changes
|
|
32
|
+
|
|
33
|
+
#### `KELVIQ_SERVER_API_KEY` follows `KELVIQ_ENV`
|
|
34
|
+
|
|
35
|
+
`KELVIQ_SERVER_API_KEY` now belongs to the environment named by `KELVIQ_ENV`, and `KELVIQ_ENV` defaults to `sandbox` — the same rules as the [MCP server](/guides/mcp-server). It previously always meant your production key.
|
|
36
|
+
|
|
37
|
+
If you keep a production key in `KELVIQ_SERVER_API_KEY`, add `KELVIQ_ENV=production` or rename the variable to `KELVIQ_PRODUCTION_SERVER_API_KEY`. Keys saved with `kelviq login` are unaffected, and commands still target production only when you pass `--prod`.
|
|
38
|
+
|
|
39
|
+
### New Features
|
|
40
|
+
|
|
41
|
+
#### Environment-named keys
|
|
42
|
+
|
|
43
|
+
`KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` always apply to their own environment and take priority over `KELVIQ_SERVER_API_KEY`, so one shell or CI job can hold both keys for `kelviq promote`.
|
|
44
|
+
|
|
45
|
+
### Improvements
|
|
46
|
+
|
|
47
|
+
- `kelviq env` shows which environment `KELVIQ_ENV` points your unprefixed variables at.
|
|
48
|
+
- When a key is missing, the error names every way to provide it, and tells you if `KELVIQ_SERVER_API_KEY` is set for the other environment.
|
|
49
|
+
- An invalid `KELVIQ_ENV` value stops the command instead of guessing.
|
|
50
|
+
|
|
51
|
+
### Fixes
|
|
52
|
+
|
|
53
|
+
- `kelviq push` now works with a globally installed CLI in projects that don't install `@kelviq/cli` locally. Previously it failed with `Cannot find package '@kelviq/cli'`.
|
|
54
|
+
|
|
55
|
+
</Update>
|
|
56
|
+
|
|
57
|
+
<Update label="v1.7.9" description="September 15, 2026" tags={["API"]}>
|
|
58
|
+
|
|
59
|
+
### New Features
|
|
60
|
+
|
|
61
|
+
#### Discounts API
|
|
62
|
+
|
|
63
|
+
Discount codes can now be managed directly through the API, authenticated with your server API key:
|
|
64
|
+
|
|
65
|
+
- `GET /discount/` — list discounts
|
|
66
|
+
- `POST /discount/` — create a discount (Merchant of Record organizations only)
|
|
67
|
+
- `GET /discount/{id}/` — retrieve a discount
|
|
68
|
+
- `PATCH /discount/{id}/` — enable or disable a discount
|
|
69
|
+
- `DELETE /discount/{id}/` — archive a discount
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"discountType": "PERCENTAGE",
|
|
74
|
+
"percentageOff": 20,
|
|
75
|
+
"name": "Summer Sale",
|
|
76
|
+
"code": "SUMMER20",
|
|
77
|
+
"duration": "ONCE"
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
See the [Discounts API reference](/api-reference/introduction) for the full request/response shape, including restricting a discount to specific products or plans with `appliesTo`.
|
|
82
|
+
|
|
83
|
+
#### Manage webhook endpoints via API
|
|
84
|
+
|
|
85
|
+
`WebhookEndpoint` resources — previously dashboard-only — are now fully manageable through the API:
|
|
86
|
+
|
|
87
|
+
- `GET /webhook/endpoints/` — list webhook endpoints
|
|
88
|
+
- `POST /webhook/endpoints/` — create a webhook endpoint
|
|
89
|
+
- `GET /webhook/endpoints/{id}/` — retrieve a webhook endpoint
|
|
90
|
+
- `PATCH /webhook/endpoints/{id}/` — update the URL, subscribed events, or enabled state
|
|
91
|
+
- `DELETE /webhook/endpoints/{id}/` — delete a webhook endpoint
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{
|
|
95
|
+
"url": "https://example.com/webhooks/kelviq",
|
|
96
|
+
"events": ["invoice.paid", "subscription.cancelled"],
|
|
97
|
+
"enabled": true
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The signing secret used to verify the `webhook-signature` header is generated automatically and returned in the create response.
|
|
102
|
+
|
|
103
|
+
</Update>
|
|
104
|
+
|
|
105
|
+
<Update label="v1.0.0" description="September 14, 2026" tags={["MCP Server"]}>
|
|
106
|
+
|
|
107
|
+
### Breaking Changes
|
|
108
|
+
|
|
109
|
+
#### Sandbox is now the default environment
|
|
110
|
+
|
|
111
|
+
When `KELVIQ_ENV` isn't set, the server now uses your **sandbox** environment instead of production, so an AI client can't change live data unless you choose production explicitly.
|
|
112
|
+
|
|
113
|
+
If you use the MCP server with a production key, add `KELVIQ_ENV=production` to its environment. Without it, requests go to the sandbox host and return 403 errors — nothing is written.
|
|
114
|
+
|
|
115
|
+
### Improvements
|
|
116
|
+
|
|
117
|
+
- The startup log shows which environment the server is using, and warns when `KELVIQ_ENV` isn't set.
|
|
118
|
+
- The server tells the connected AI client which environment its tools act on.
|
|
119
|
+
- 401 and 403 errors now include a hint: when `KELVIQ_ENV` isn't set, they explain the sandbox default and how to use a production key; otherwise they name the active environment and link its API keys page.
|
|
120
|
+
- Setup examples now run `npx -y @kelviq/mcp-server@latest`, so clients pick up new releases instead of a cached copy.
|
|
121
|
+
|
|
122
|
+
### Fixes
|
|
123
|
+
|
|
124
|
+
- If your MCP client passes an unexpanded placeholder such as `${KELVIQ_ENV}` instead of a value, the server now treats that variable as unset and warns at startup. Previously the server failed to start, or sent the placeholder text as your API key.
|
|
125
|
+
|
|
126
|
+
</Update>
|
|
127
|
+
|
|
128
|
+
<Update label="v1.7.8" description="September 10, 2026" tags={["API"]}>
|
|
129
|
+
|
|
130
|
+
### New Features
|
|
131
|
+
|
|
132
|
+
#### Limit checkout to selected billing periods
|
|
133
|
+
|
|
134
|
+
`POST /checkout/` now accepts `billingPeriodsEnabled`, a comma-separated list of billing periods to display and allow during checkout. Values are case-insensitive and normalized to uppercase. A checkout attempt using a billing period outside this list is rejected.
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"planIdentifier": "premium-plan",
|
|
139
|
+
"chargePeriod": "MONTHLY",
|
|
140
|
+
"billingPeriodsEnabled": "MONTHLY,YEARLY",
|
|
141
|
+
"successUrl": "https://example.com/checkout/success"
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`GET /monetization/product-offering/{product_id}/` also accepts `billing_periods_enabled` to return only the requested billing periods. Static checkout links support the same snake-case parameter.
|
|
146
|
+
|
|
147
|
+
#### Prefill the checkout email address
|
|
148
|
+
|
|
149
|
+
`POST /checkout/` now accepts `email` to prefill the checkout page. Combine it with `lockEmail: true` when the customer must not edit the address.
|
|
150
|
+
|
|
151
|
+
```json
|
|
152
|
+
{
|
|
153
|
+
"planIdentifier": "premium-plan",
|
|
154
|
+
"chargePeriod": "MONTHLY",
|
|
155
|
+
"email": "customer@example.com",
|
|
156
|
+
"lockEmail": true,
|
|
157
|
+
"successUrl": "https://example.com/checkout/success"
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Static checkout links can prefill the same value with the `email` query parameter.
|
|
162
|
+
|
|
163
|
+
</Update>
|
|
164
|
+
|
|
165
|
+
<Update label="v2.8.0" description="September 9, 2026" tags={["Node SDK"]}>
|
|
166
|
+
|
|
167
|
+
### New Features
|
|
168
|
+
|
|
169
|
+
#### Refunds
|
|
170
|
+
|
|
171
|
+
A new `client.refunds` module lets you list, create, and retrieve refunds.
|
|
172
|
+
|
|
173
|
+
```typescript
|
|
174
|
+
const refund = await client.refunds.create({
|
|
175
|
+
orderId: "ORD-20260715123000-A1B2C",
|
|
176
|
+
amountUnits: 2500,
|
|
177
|
+
reason: "REQUESTED_BY_CUSTOMER",
|
|
178
|
+
internalNote: "Customer requested a partial refund.",
|
|
179
|
+
});
|
|
180
|
+
|
|
181
|
+
const page = await client.refunds.list({ status: "SUCCEEDED", page: 1, pageSize: 10 });
|
|
182
|
+
|
|
183
|
+
const retrieved = await client.refunds.retrieve({ refundId: refund.id });
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`client.refunds.create()` accepts either `amountUnits` (minor currency unit) or `amount` (major currency unit) for a partial refund; omit both to refund the order's entire remaining refundable balance. `client.refunds.list()` supports `search`, `status`, `startDate`, `endDate`, `page`, and `pageSize` filters.
|
|
187
|
+
|
|
188
|
+
#### Payment Methods
|
|
189
|
+
|
|
190
|
+
A new `client.paymentMethods` module lists saved payment methods, optionally filtered by `customerId` or `customerEmail`.
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
const methods = await client.paymentMethods.list({ customerId: "cust_789" });
|
|
194
|
+
console.log(methods.results[0].methodData.brand, methods.results[0].methodData.last4);
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Only payment methods with status `succeeded` are returned.
|
|
198
|
+
|
|
199
|
+
#### Transactions
|
|
200
|
+
|
|
201
|
+
A new `client.transactions` module lists financial transactions, including the itemized Merchant of Record fee breakdown when applicable.
|
|
202
|
+
|
|
203
|
+
```typescript
|
|
204
|
+
const transactions = await client.transactions.list({ status: "success", startDate: "2026-07-01" });
|
|
205
|
+
console.log(transactions.results[0].amountTotal, transactions.results[0].morFeeBreakdown);
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
`client.transactions.list()` supports `search`, `status`, `startDate`, `endDate`, `page`, and `pageSize` filters.
|
|
209
|
+
|
|
210
|
+
</Update>
|
|
211
|
+
|
|
212
|
+
<Update label="v2.8.0" description="September 9, 2026" tags={["Python SDK"]}>
|
|
213
|
+
|
|
214
|
+
### New Features
|
|
215
|
+
|
|
216
|
+
#### Refunds
|
|
217
|
+
|
|
218
|
+
The synchronous and asynchronous clients now provide a `refunds` module for listing, creating, and retrieving refunds.
|
|
219
|
+
|
|
220
|
+
```python
|
|
221
|
+
refund = client.refunds.create(
|
|
222
|
+
orderId="ORD-20260715123000-A1B2C",
|
|
223
|
+
amountUnits=2500,
|
|
224
|
+
reason="REQUESTED_BY_CUSTOMER",
|
|
225
|
+
internalNote="Customer requested a partial refund.",
|
|
226
|
+
)
|
|
227
|
+
|
|
228
|
+
page = client.refunds.list(status="SUCCEEDED", page=1, page_size=10)
|
|
229
|
+
|
|
230
|
+
retrieved = client.refunds.retrieve(refund.id)
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
**Async variant:**
|
|
234
|
+
|
|
235
|
+
```python
|
|
236
|
+
refund = await async_client.refunds.create(
|
|
237
|
+
orderId="ORD-20260715123000-A1B2C",
|
|
238
|
+
amountUnits=2500,
|
|
239
|
+
)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
`client.refunds.create()` accepts either `amountUnits` (minor currency unit) or `amount` (major currency unit) for a partial refund; omit both to refund the order's entire remaining refundable balance. `client.refunds.list()` supports `search`, `status`, `start_date`, `end_date`, `page`, and `page_size` filters. Pydantic models validate parameters and provide typed refund records.
|
|
243
|
+
|
|
244
|
+
#### Payment Methods
|
|
245
|
+
|
|
246
|
+
The synchronous and asynchronous clients now provide a `payment_methods` module that lists saved payment methods, optionally filtered by `customer_id` or `customer_email`.
|
|
247
|
+
|
|
248
|
+
```python
|
|
249
|
+
methods = client.payment_methods.list(customer_id="cust_789")
|
|
250
|
+
print(methods.results[0].methodData["brand"], methods.results[0].methodData["last4"])
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Only payment methods with status `succeeded` are returned.
|
|
254
|
+
|
|
255
|
+
#### Transactions
|
|
256
|
+
|
|
257
|
+
The synchronous and asynchronous clients now provide a `transactions` module that lists financial transactions, including the itemized Merchant of Record fee breakdown when applicable.
|
|
258
|
+
|
|
259
|
+
```python
|
|
260
|
+
transactions = client.transactions.list(status="success", start_date="2026-07-01")
|
|
261
|
+
print(transactions.results[0].amountTotal, transactions.results[0].morFeeBreakdown)
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
`client.transactions.list()` supports `search`, `status`, `start_date`, `end_date`, `page`, and `page_size` filters.
|
|
265
|
+
|
|
266
|
+
</Update>
|
|
267
|
+
|
|
268
|
+
<Update label="v2.7.4" description="September 8, 2026" tags={["Node SDK"]}>
|
|
269
|
+
|
|
270
|
+
### New Features
|
|
271
|
+
|
|
272
|
+
#### Control How Subscription Updates Are Billed
|
|
273
|
+
|
|
274
|
+
`client.subscriptions.update()` now supports `prorationBehavior`, using the exported `PRORATION_BEHAVIORS` constant. It controls when the customer is billed for a mid-period change: `IMMEDIATE_CHARGE` invoices the difference right now, `PRORATE_NEXT_INVOICE` bills it on the next invoice, and `NO_PRORATION` changes the plan without crediting or charging for the partial period.
|
|
275
|
+
|
|
276
|
+
```typescript
|
|
277
|
+
import { CHARGE_PERIOD_CHOICES, PRORATION_BEHAVIORS } from "@kelviq/node-sdk";
|
|
278
|
+
|
|
279
|
+
const subscription = await client.subscriptions.update({
|
|
280
|
+
subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
281
|
+
planIdentifier: "premium-plan",
|
|
282
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
283
|
+
prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
|
|
284
|
+
});
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
The SDK serializes the option as `proration_behavior`. Omit it to use your organization's default.
|
|
288
|
+
|
|
289
|
+
Changing `chargePeriod` to a different billing interval resets the billing cycle and invoices the new period immediately, whichever value you pass — with `NO_PRORATION`, without any credit for unused time on the old plan.
|
|
290
|
+
|
|
291
|
+
#### Preview Subscription Updates
|
|
292
|
+
|
|
293
|
+
`client.subscriptions.previewUpdate()` calculates the financial effect of a proposed subscription update without changing the subscription, creating an invoice, or charging the customer. It accepts the same plan, charge period, proration behavior, features, IP address, and trial-end options used by an update.
|
|
294
|
+
|
|
295
|
+
```typescript
|
|
296
|
+
const preview = await client.subscriptions.previewUpdate({
|
|
297
|
+
subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
298
|
+
planIdentifier: "premium-plan",
|
|
299
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.YEARLY,
|
|
300
|
+
prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
|
|
301
|
+
features: [{ identifier: "seats", quantity: 10 }],
|
|
302
|
+
});
|
|
303
|
+
|
|
304
|
+
console.log(preview.recurringAmount, preview.amountChargedImmediately);
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
The response includes typed major- and minor-unit amounts, the next payment attempt, and preview invoice line items.
|
|
308
|
+
|
|
309
|
+
#### Set a Custom Trial Period at Checkout
|
|
310
|
+
|
|
311
|
+
`client.checkout.createSession()` now accepts `trialPeriod`. Pass an integer greater than or equal to `1` to override the selected plan's configured trial period. Invalid values are rejected by the SDK before a request is sent.
|
|
312
|
+
|
|
313
|
+
```typescript
|
|
314
|
+
const session = await client.checkout.createSession({
|
|
315
|
+
planIdentifier: "premium-plan",
|
|
316
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
317
|
+
successUrl: "https://example.com/checkout/success",
|
|
318
|
+
trialPeriod: 14,
|
|
319
|
+
});
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
#### Use a Custom Amount for One-Time Charges
|
|
323
|
+
|
|
324
|
+
`client.charges.create()` now accepts `customAmount` and `taxBehavior`. `customAmount` must be greater than zero and requires `currencyCode`; `taxBehavior` accepts `INCLUSIVE` or `EXCLUSIVE`.
|
|
325
|
+
|
|
326
|
+
```typescript
|
|
327
|
+
const charge = await client.charges.create({
|
|
328
|
+
planIdentifier: "lifetime-access",
|
|
329
|
+
chargePeriod: "ONE_TIME",
|
|
330
|
+
customerId: "cust_789",
|
|
331
|
+
currencyCode: "USD",
|
|
332
|
+
customAmount: 49.99,
|
|
333
|
+
taxBehavior: "INCLUSIVE",
|
|
334
|
+
});
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
### Deprecations
|
|
338
|
+
|
|
339
|
+
`probationBehaviour` and `PROBATION_BEHAVIOURS` are deprecated in favour of `prorationBehavior` and `PRORATION_BEHAVIORS` (`probation` was a typo for `proration`). The old field still works.
|
|
340
|
+
|
|
341
|
+
`PROBATION_BEHAVIOURS.NEXT_BILLING_CYCLE` and `PROBATION_BEHAVIOURS.PRO_RATA` were never supported by the API and are rejected by it. Use `PRORATION_BEHAVIORS.NO_PRORATION` and `PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE` instead. `IMMEDIATE_CHARGE` is unchanged and now works.
|
|
342
|
+
|
|
343
|
+
</Update>
|
|
344
|
+
|
|
345
|
+
<Update label="v2.7.4" description="September 8, 2026" tags={["Python SDK"]}>
|
|
346
|
+
|
|
347
|
+
### New Features
|
|
348
|
+
|
|
349
|
+
#### Control How Subscription Updates Are Billed
|
|
350
|
+
|
|
351
|
+
The synchronous and asynchronous `client.subscriptions.update()` methods now support `prorationBehavior`, with a `ProrationBehavior` enum exported from the package. It controls when the customer is billed for a mid-period change: `IMMEDIATE_CHARGE` invoices the difference right now, `PRORATE_NEXT_INVOICE` bills it on the next invoice, and `NO_PRORATION` changes the plan without crediting or charging for the partial period.
|
|
352
|
+
|
|
353
|
+
```python
|
|
354
|
+
from kelviq_sdk import ProrationBehavior
|
|
355
|
+
|
|
356
|
+
subscription = client.subscriptions.update(
|
|
357
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
358
|
+
planIdentifier="premium-plan",
|
|
359
|
+
chargePeriod="MONTHLY",
|
|
360
|
+
prorationBehavior=ProrationBehavior.PRORATE_NEXT_INVOICE,
|
|
361
|
+
)
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
The SDK validates the value and serializes it as `proration_behavior`. Omit it to use your organization's default.
|
|
365
|
+
|
|
366
|
+
Changing `chargePeriod` to a different billing interval resets the billing cycle and invoices the new period immediately, whichever value you pass — with `NO_PRORATION`, without any credit for unused time on the old plan.
|
|
367
|
+
|
|
368
|
+
#### Preview Subscription Updates
|
|
369
|
+
|
|
370
|
+
The synchronous and asynchronous subscription clients now provide `preview_update()`. It calculates the financial effect of a proposed update without changing the subscription, creating an invoice, or charging the customer.
|
|
371
|
+
|
|
372
|
+
```python
|
|
373
|
+
preview = client.subscriptions.preview_update(
|
|
374
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
375
|
+
planIdentifier="premium-plan",
|
|
376
|
+
chargePeriod="YEARLY",
|
|
377
|
+
prorationBehavior=ProrationBehavior.PRORATE_NEXT_INVOICE,
|
|
378
|
+
features=[{"identifier": "seats", "quantity": 10}],
|
|
379
|
+
)
|
|
380
|
+
|
|
381
|
+
print(preview.recurringAmount, preview.amountChargedImmediately)
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
The returned Pydantic models include major- and minor-unit amounts, the next payment attempt, and preview invoice line items.
|
|
385
|
+
|
|
386
|
+
#### Set a Custom Trial Period at Checkout
|
|
387
|
+
|
|
388
|
+
The synchronous and asynchronous `checkout.create_session()` methods now accept `trialPeriod`. Pass an integer greater than or equal to `1` to override the selected plan's configured trial period.
|
|
389
|
+
|
|
390
|
+
```python
|
|
391
|
+
session = client.checkout.create_session(
|
|
392
|
+
planIdentifier="premium-plan",
|
|
393
|
+
chargePeriod="MONTHLY",
|
|
394
|
+
successUrl="https://example.com/checkout/success",
|
|
395
|
+
trialPeriod=14,
|
|
396
|
+
)
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
#### Use a Custom Amount for One-Time Charges
|
|
400
|
+
|
|
401
|
+
The synchronous and asynchronous `charges.create()` methods now accept `customAmount` and `taxBehavior`. `customAmount` must be greater than zero and requires `currencyCode`; `taxBehavior` accepts `INCLUSIVE` or `EXCLUSIVE`.
|
|
402
|
+
|
|
403
|
+
```python
|
|
404
|
+
charge = client.charges.create(
|
|
405
|
+
planIdentifier="lifetime-access",
|
|
406
|
+
chargePeriod="ONE_TIME",
|
|
407
|
+
customerId="cust_789",
|
|
408
|
+
currencyCode="USD",
|
|
409
|
+
customAmount=49.99,
|
|
410
|
+
taxBehavior="INCLUSIVE",
|
|
411
|
+
)
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
### Changes
|
|
415
|
+
|
|
416
|
+
`successUrl` is now required when calling the synchronous or asynchronous `checkout.create_session()` method, matching the API contract.
|
|
417
|
+
|
|
418
|
+
### Deprecations
|
|
419
|
+
|
|
420
|
+
`probationBehaviour` is deprecated in favour of `prorationBehavior` (`probation` was a typo for `proration`). It is still accepted and continues to serialize as `probation_behaviour`.
|
|
421
|
+
|
|
422
|
+
</Update>
|
|
423
|
+
|
|
424
|
+
<Update label="v1.7.7" description="September 7, 2026" tags={["API"]}>
|
|
425
|
+
|
|
426
|
+
### New Features
|
|
427
|
+
|
|
428
|
+
#### Set a custom trial period at checkout
|
|
429
|
+
|
|
430
|
+
`POST /checkout/` now accepts `trialPeriod`, allowing you to set the number of trial days for the subscription created by a checkout session. When provided, it overrides the trial period configured on the selected plan.
|
|
431
|
+
|
|
432
|
+
```json
|
|
433
|
+
{
|
|
434
|
+
"planIdentifier": "premium-plan",
|
|
435
|
+
"chargePeriod": "MONTHLY",
|
|
436
|
+
"trialPeriod": 14,
|
|
437
|
+
"successUrl": "https://example.com/checkout/success"
|
|
438
|
+
}
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
### Changes
|
|
442
|
+
|
|
443
|
+
#### Success URL is required
|
|
444
|
+
|
|
445
|
+
`successUrl` is mandatory when calling `POST /checkout/`. Requests that omit it are rejected with a `400` response.
|
|
446
|
+
|
|
447
|
+
</Update>
|
|
448
|
+
|
|
449
|
+
<Update label="v1.17" description="August 21, 2026" tags={["App"]}>
|
|
450
|
+
|
|
451
|
+
## Find transactions faster
|
|
452
|
+
|
|
453
|
+
Search on the **Payouts → Transactions** page now works properly, and filtering is more precise:
|
|
454
|
+
|
|
455
|
+
* A status filter narrows the list to successful, failed, or pending transactions.
|
|
456
|
+
* The search field matches payment method types. Search for `upi`, `card`, `link`, `amazon_pay`, or `sepa_debit` to see payments made through that method.
|
|
457
|
+
|
|
458
|
+
## Migrate subscriptions to the latest plan version
|
|
459
|
+
|
|
460
|
+
When you republish a plan with new pricing or entitlements, existing subscribers stay on the version they bought. You can now move them forward. The migrate action on a subscription updates it to the latest version of its plan, and it is available in two places: the dashboard, and the customer portal, where customers can migrate their own subscription.
|
|
461
|
+
|
|
462
|
+
Custom-priced subscriptions cannot be migrated. Developers can run the same migration with `POST /subscriptions/{subscriptionId}/migrate/` and control how the change is billed with the organization's proration defaults. The [API changelog](/changelog#api) has the details.
|
|
463
|
+
|
|
464
|
+
</Update>
|
|
465
|
+
|
|
466
|
+
<Update label="v1.7.6" description="August 20, 2026" tags={["API"]}>
|
|
467
|
+
|
|
468
|
+
### New Features
|
|
469
|
+
|
|
470
|
+
#### Organization-level proration defaults
|
|
471
|
+
|
|
472
|
+
`GET /organizations/settings/` and `PATCH /organizations/settings/` now expose two settings for controlling how subscription changes are prorated:
|
|
473
|
+
|
|
474
|
+
| Setting | Default | Used when |
|
|
475
|
+
| --- | --- | --- |
|
|
476
|
+
| `updateSubscriptionProrationBehavior` | `IMMEDIATE_CHARGE` | A subscription is upgraded or downgraded without a `prorationBehavior` in the update request. |
|
|
477
|
+
| `migrateSubscriptionProrationBehavior` | `PRORATE_NEXT_INVOICE` | A subscription is migrated to the latest version of its plan. |
|
|
478
|
+
|
|
479
|
+
Both settings accept `IMMEDIATE_CHARGE`, `PRORATE_NEXT_INVOICE`, or `NO_PRORATION`.
|
|
480
|
+
|
|
481
|
+
```json
|
|
482
|
+
{
|
|
483
|
+
"updateSubscriptionProrationBehavior": "IMMEDIATE_CHARGE",
|
|
484
|
+
"migrateSubscriptionProrationBehavior": "PRORATE_NEXT_INVOICE"
|
|
485
|
+
}
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
#### Organization checkout customization
|
|
489
|
+
|
|
490
|
+
Checkout branding and appearance can now be stored as organization defaults. Use `GET /organizations/checkout-settings/` to retrieve the settings and `PATCH /organizations/checkout-settings/` to update the brand name, light and dark logos, favicon, background image, and checkout customization object.
|
|
491
|
+
|
|
492
|
+
The hosted checkout session response now includes these settings so the organization's branding can be applied consistently across checkout sessions.
|
|
493
|
+
|
|
494
|
+
#### Migrate individual subscriptions
|
|
495
|
+
|
|
496
|
+
`POST /subscriptions/{subscriptionId}/migrate/` migrates an existing subscription to the latest version of its current plan. Set at least one of `updateFeatures` or `updatePricing` to `true`:
|
|
497
|
+
|
|
498
|
+
```json
|
|
499
|
+
{
|
|
500
|
+
"updateFeatures": true,
|
|
501
|
+
"updatePricing": true
|
|
502
|
+
}
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
The migration action is now available from both the Kelviq dashboard and the customer portal. Customer-portal migrations are restricted to the signed-in customer's own subscription. Custom-priced subscriptions cannot be migrated.
|
|
506
|
+
|
|
507
|
+
### Changes
|
|
508
|
+
|
|
509
|
+
#### Identify custom-priced subscriptions
|
|
510
|
+
|
|
511
|
+
`GET /subscriptions/` and `GET /subscriptions/{subscriptionId}/` now include `isCustomPricing`. It is `true` when the subscription uses a custom price instead of the plan's configured price, and `false` otherwise.
|
|
512
|
+
|
|
513
|
+
```json
|
|
514
|
+
{
|
|
515
|
+
"id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
|
|
516
|
+
"isCustomPricing": true
|
|
517
|
+
}
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
</Update>
|
|
521
|
+
|
|
522
|
+
<Update label="v1.7.5" description="August 14, 2026" tags={["API"]}>
|
|
523
|
+
|
|
524
|
+
### New Features
|
|
525
|
+
|
|
526
|
+
#### Control how subscription updates are billed
|
|
527
|
+
|
|
528
|
+
`POST /subscriptions/{subscriptionId}/update/` and its `/preview/` counterpart now accept `prorationBehavior`, which controls when the customer is billed for a mid-period change:
|
|
529
|
+
|
|
530
|
+
| Value | Effect |
|
|
531
|
+
| --- | --- |
|
|
532
|
+
| `IMMEDIATE_CHARGE` | Prorates and invoices the difference right now. |
|
|
533
|
+
| `PRORATE_NEXT_INVOICE` | Prorates now, but bills it on the next invoice. |
|
|
534
|
+
| `NO_PRORATION` | Changes the plan immediately without crediting or charging for the partial period; the next invoice bills the full new price. |
|
|
535
|
+
|
|
536
|
+
If omitted, your organization's existing default is used, so existing integrations are unaffected.
|
|
537
|
+
|
|
538
|
+
```json
|
|
539
|
+
{
|
|
540
|
+
"planIdentifier": "premium-plan",
|
|
541
|
+
"chargePeriod": "MONTHLY",
|
|
542
|
+
"prorationBehavior": "PRORATE_NEXT_INVOICE"
|
|
543
|
+
}
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
Invalid values are now rejected with a clear `400` naming the accepted values, instead of a generic error.
|
|
547
|
+
|
|
548
|
+
Changing `chargePeriod` to a different billing interval (for example `MONTHLY` to `YEARLY`) resets the billing cycle and invoices the new period immediately, whichever `prorationBehavior` you pass. With `NO_PRORATION` the customer is charged for a full new period with no credit for unused time on the old plan. Call the preview endpoint first to see the exact amount.
|
|
549
|
+
|
|
550
|
+
### Improvements
|
|
551
|
+
|
|
552
|
+
`amountChargedImmediately` on the update preview endpoint is now correct for billing-interval changes. It previously reported `0` for a `MONTHLY` to `YEARLY` change unless `prorationBehavior` was `IMMEDIATE_CHARGE`, even though the customer was charged right away.
|
|
553
|
+
|
|
554
|
+
### Deprecations
|
|
555
|
+
|
|
556
|
+
The undocumented `probation_behaviour` request field is deprecated in favour of `prorationBehavior` (`probation` was a typo for `proration`). It is still accepted and continues to work unchanged.
|
|
557
|
+
|
|
558
|
+
</Update>
|
|
559
|
+
|
|
560
|
+
<Update label="v1.7.4" description="August 12, 2026" tags={["API"]}>
|
|
561
|
+
|
|
562
|
+
### New Features
|
|
563
|
+
|
|
564
|
+
#### Preview subscription updates
|
|
565
|
+
|
|
566
|
+
Use `POST /subscriptions/{subscriptionId}/update/preview/` to see the financial effect of a plan, billing-period, or feature change before applying it. Send the same `planIdentifier`, `chargePeriod`, and `features` payload used to update a subscription.
|
|
567
|
+
|
|
568
|
+
The response includes the new recurring amount, any amount that would be charged immediately, and the previewed next invoice with its line items. Amounts are returned in both major currency units and integer minor units. The preview does not update the subscription, create an invoice, or charge the customer.
|
|
569
|
+
|
|
570
|
+
```json
|
|
571
|
+
{
|
|
572
|
+
"currency": "USD",
|
|
573
|
+
"recurringAmount": 50,
|
|
574
|
+
"recurringAmountUnits": 5000,
|
|
575
|
+
"amountChargedImmediately": 39.5,
|
|
576
|
+
"amountChargedImmediatelyUnits": 3950,
|
|
577
|
+
"nextInvoice": {
|
|
578
|
+
"amountDue": 39.5,
|
|
579
|
+
"amountDueUnits": 3950,
|
|
580
|
+
"nextPaymentAttempt": "2026-09-01T00:00:00Z",
|
|
581
|
+
"lineItems": [
|
|
582
|
+
{
|
|
583
|
+
"description": "Remaining time on Enterprise after 12 Aug 2026",
|
|
584
|
+
"amount": 39.5,
|
|
585
|
+
"amountUnits": 3950
|
|
586
|
+
}
|
|
587
|
+
]
|
|
588
|
+
}
|
|
589
|
+
}
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
#### Custom amounts for one-time charges
|
|
593
|
+
|
|
594
|
+
`POST /charges/` now accepts `customAmount` to override a plan's configured one-time price. Pass the amount in the currency's major unit and include `currencyCode`. You can also set `taxBehavior` to `INCLUSIVE` or `EXCLUSIVE`; it defaults to `EXCLUSIVE`.
|
|
595
|
+
|
|
596
|
+
```json
|
|
597
|
+
{
|
|
598
|
+
"planIdentifier": "lifetime-access",
|
|
599
|
+
"chargePeriod": "ONE_TIME",
|
|
600
|
+
"customerId": "cust_789",
|
|
601
|
+
"currencyCode": "USD",
|
|
602
|
+
"customAmount": 49.99,
|
|
603
|
+
"taxBehavior": "INCLUSIVE"
|
|
604
|
+
}
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
</Update>
|
|
608
|
+
|
|
609
|
+
<Update label="v1.7.3" description="August 10, 2026" tags={["API"]}>
|
|
610
|
+
|
|
611
|
+
### New Features
|
|
612
|
+
|
|
613
|
+
#### Trial ending webhook
|
|
614
|
+
|
|
615
|
+
You can now subscribe to `subscription.trial_will_end`. Kelviq sends this a few days before a subscription's trial ends, mirroring Stripe's own `customer.subscription.trial_will_end` timing. It's skipped if the subscription has already converted to `active` or has no trial days left by the time the notice would go out. `data.object` uses the same subscription payload shape as `subscription.created` and `subscription.updated`.
|
|
616
|
+
|
|
617
|
+
</Update>
|
|
618
|
+
|
|
619
|
+
<Update label="v1.7.2" description="August 10, 2026" tags={["API"]}>
|
|
620
|
+
|
|
621
|
+
### New Features
|
|
622
|
+
|
|
623
|
+
#### Invoices API
|
|
624
|
+
|
|
625
|
+
You can now list and retrieve invoices directly, rather than only receiving them through webhooks:
|
|
626
|
+
|
|
627
|
+
- `GET /invoices/` — a paginated list of invoices for your organization, filterable by `subscription_id` and `customer_id`.
|
|
628
|
+
- `GET /invoices/{invoiceId}/` — a single invoice by its Kelviq invoice ID.
|
|
629
|
+
|
|
630
|
+
The invoice object also has three new fields, matching what's already sent in invoice webhooks:
|
|
631
|
+
|
|
632
|
+
- `attemptCount` — number of payment attempts made against the invoice.
|
|
633
|
+
- `nextPaymentAttempt` — when Stripe will next retry collection, if a retry is scheduled.
|
|
634
|
+
- `failureDetails` — `code`, `message`, and `paymentMethodType` for the most recent failed payment attempt. `null` once the invoice is paid.
|
|
635
|
+
|
|
636
|
+
#### Filter subscriptions by modification date
|
|
637
|
+
|
|
638
|
+
`GET /subscriptions/` now accepts `modified_on_after` / `modified_on_before` query parameters, for filtering by when the subscription was last modified.
|
|
639
|
+
|
|
640
|
+
```
|
|
641
|
+
GET /subscriptions/?modified_on_after=2026-08-01T00:00:00Z
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
#### Subscription timestamps
|
|
645
|
+
|
|
646
|
+
`GET /subscriptions/` and `GET /subscriptions/{subscriptionId}/` now return `createdOn` and `modifiedOn` on the subscription object.
|
|
647
|
+
|
|
648
|
+
</Update>
|
|
649
|
+
|
|
650
|
+
<Update label="v1.16" description="August 7, 2026" tags={["App"]}>
|
|
651
|
+
|
|
652
|
+
## Clearer subscription cancellation dates
|
|
653
|
+
|
|
654
|
+
Two fixes for cancelled subscriptions:
|
|
655
|
+
|
|
656
|
+
* The customer details page now shows when a subscription was cancelled, alongside its status.
|
|
657
|
+
* Cancelling a subscription from the dashboard now selects the correct cancellation date.
|
|
658
|
+
|
|
659
|
+
On the API side, subscription responses now include cancellation metadata: when the subscription was cancelled, whether the customer or the merchant initiated it, and any feedback the customer gave. See the [API changelog](/changelog#v1-7-0) entry for v1.7.0.
|
|
660
|
+
|
|
661
|
+
</Update>
|
|
662
|
+
|
|
663
|
+
<Update label="v1.7.1" description="August 5, 2026" tags={["API"]}>
|
|
664
|
+
|
|
665
|
+
### New Features
|
|
666
|
+
|
|
667
|
+
#### Payment links in invoice webhooks
|
|
668
|
+
|
|
669
|
+
The invoice object sent by `invoice.created`, `invoice.paid`, and `invoice.payment_failed` now includes `payment_link`. This URL takes the customer directly to the invoice payment page, so integrations can surface payment recovery without constructing the link themselves.
|
|
670
|
+
|
|
671
|
+
`payment_link` is present when the invoice is open or payment has failed. If the invoice is already paid when it is created, `payment_link` is `null` because no payment action is required.
|
|
672
|
+
|
|
673
|
+
Example:
|
|
674
|
+
|
|
675
|
+
```json
|
|
676
|
+
{
|
|
677
|
+
"paymentLink": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz"
|
|
678
|
+
}
|
|
679
|
+
```
|
|
680
|
+
|
|
681
|
+
### Changes
|
|
682
|
+
|
|
683
|
+
#### Portal sessions require a customer email
|
|
684
|
+
|
|
685
|
+
`POST /portal/session/` now returns `400 Bad Request` when the selected customer does not have an email address. Portal session tokens are tied to the customer's email, so add an email to the customer before creating a session.
|
|
686
|
+
|
|
687
|
+
</Update>
|
|
688
|
+
|
|
689
|
+
<Update label="v1.7.0" description="August 1, 2026" tags={["API"]}>
|
|
690
|
+
|
|
691
|
+
### New Features
|
|
692
|
+
|
|
693
|
+
#### Subscription cancellation details
|
|
694
|
+
|
|
695
|
+
`GET /subscriptions/` and `GET /subscriptions/{subscriptionId}/` now return cancellation metadata:
|
|
696
|
+
|
|
697
|
+
- `canceledAt` — when the cancellation was recorded.
|
|
698
|
+
- `cancellationReason` — whether it was initiated by the customer, merchant, or provider.
|
|
699
|
+
- `cancellationFeedback` — structured feedback such as `TOO_EXPENSIVE`, `MISSING_FEATURES`, or `UNUSED`.
|
|
700
|
+
- `cancellationComment` — an optional free-form comment.
|
|
701
|
+
|
|
702
|
+
`POST /subscriptions/{subscriptionId}/cancel/` now accepts the optional `cancellationFeedback` and `cancellationComment` fields. The cancellation endpoint records the merchant as the initiator; cancellations submitted through the customer portal record the customer as the initiator.
|
|
703
|
+
|
|
704
|
+
#### Failed invoice webhook
|
|
705
|
+
|
|
706
|
+
You can now subscribe to `invoice.payment_failed`. Kelviq sends this event when a subscription invoice payment fails or requires customer action. Its `data.object` uses the same invoice payload shape as `invoice.created` and `invoice.paid`.
|
|
707
|
+
|
|
708
|
+
#### Refund webhook context
|
|
709
|
+
|
|
710
|
+
The `refund.created` and `refund.updated` webhook objects now include:
|
|
711
|
+
|
|
712
|
+
- `customer` — the associated customer's ID, name, email, customer identifier, and billing address.
|
|
713
|
+
- `subscription_id` — the associated subscription ID, or `null` for an order without a subscription.
|
|
714
|
+
|
|
715
|
+
#### Refunded order total
|
|
716
|
+
|
|
717
|
+
Order responses from `GET /orders/` and `GET /orders/{id}/` now include `refundedTotalUnits`, the total amount refunded against the order in the sale currency's minor units.
|
|
718
|
+
|
|
719
|
+
</Update>
|
|
720
|
+
|
|
721
|
+
<Update label="v1.15" description="July 31, 2026" tags={["App"]}>
|
|
722
|
+
|
|
723
|
+
## Kelviq now covers your payout fees
|
|
724
|
+
|
|
725
|
+
Payout fees are on us. When your cleared Kelviq balance is sent to your bank account or eligible debit card, Kelviq bears the provider's payout costs. You keep the full amount of your balance, and transaction fees are unchanged.
|
|
726
|
+
|
|
727
|
+
See [Fees](/getstarted/fees) for what a transaction costs and [Payouts](/payouts/overview) for how balances reach your bank.
|
|
728
|
+
|
|
729
|
+
## More billing periods
|
|
730
|
+
|
|
731
|
+
Plans now support a six-month billing period alongside monthly, quarterly, and yearly.
|
|
732
|
+
|
|
733
|
+
Plans can also bill on a fixed four-week cycle. Renewals happen on the same weekday every 28 days, and metered features can reset usage on the same 28-day schedule instead of following calendar months.
|
|
734
|
+
|
|
735
|
+
The 28-day period, and other custom periods such as weekly or daily, must be enabled for your organization first. Contact [hi@kelviq.com](mailto:hi@kelviq.com) to turn them on.
|
|
736
|
+
|
|
737
|
+
## Trials now default to 7 days
|
|
738
|
+
|
|
739
|
+
New free trials default to 7 days instead of 30. You can still set any duration from 1 to 365 days.
|
|
740
|
+
|
|
741
|
+
</Update>
|
|
742
|
+
|
|
743
|
+
<Update label="v1.6.3" description="July 29, 2026" tags={["API"]}>
|
|
744
|
+
|
|
745
|
+
### Fixes
|
|
746
|
+
|
|
747
|
+
#### `subscription.updated` now fires when a cancellation is scheduled for period-end
|
|
748
|
+
|
|
749
|
+
Scheduling a subscription to cancel at the end of the current billing period (rather than immediately) previously sent no webhook at all — status stays `active` until the period actually ends, so nothing was detected as changed. This now correctly sends `subscription.updated` (with the new `end_date` and a `previous_attributes.end_date` of `null`) at the moment the cancellation is scheduled. `subscription.cancelled` still only fires once the subscription actually reaches cancelled status — for a period-end cancellation, that's later, when the period ends.
|
|
750
|
+
|
|
751
|
+
</Update>
|
|
752
|
+
|
|
753
|
+
<Update label="v1.6.2" description="July 29, 2026" tags={["API"]}>
|
|
754
|
+
|
|
755
|
+
### New Features
|
|
756
|
+
|
|
757
|
+
#### Checkout sessions and checkout session events
|
|
758
|
+
|
|
759
|
+
Three endpoints are now part of the public API:
|
|
760
|
+
|
|
761
|
+
- `GET /checkout/sessions/` — paginated list of checkout sessions for the authenticated organization.
|
|
762
|
+
- `GET /checkout/sessions/{session_id}/` — a single checkout session, including the order, subscription, and payment method it produced (if any).
|
|
763
|
+
- `GET /checkout/sessions/{session_id}/events/` — the session's timeline events (session created, customer details updated, payment attempted, payment completed, etc.).
|
|
764
|
+
|
|
765
|
+
</Update>
|
|
766
|
+
|
|
767
|
+
<Update label="v1.6.1" description="July 29, 2026" tags={["API"]}>
|
|
768
|
+
|
|
769
|
+
### New Features
|
|
770
|
+
|
|
771
|
+
#### Orders, order events, and webhook delivery logs
|
|
772
|
+
|
|
773
|
+
Four endpoints are now part of the public API:
|
|
774
|
+
|
|
775
|
+
- `GET /orders/` — paginated list of orders. `PENDING` orders (payment never attempted/completed) are never included. Accepts `status`, `billing_type` (`ONE_TIME`/`SUBSCRIPTION`), and `is_renewal` (`true`/`false`) filters.
|
|
776
|
+
- `GET /orders/{id}/` — a single order.
|
|
777
|
+
- `GET /orders/{id}/events/` — the order's timeline events (order created, order completed, order receipt sent, invoice paid, etc.). This returns events for every order tied to the same underlying subscription as `{id}`, not just that single order record.
|
|
778
|
+
- `GET /webhook/logs/` — one row per webhook delivery attempt, including retries.
|
|
779
|
+
|
|
780
|
+
`GET /webhook/logs/` also accepts `start_date`/`end_date` query params. Results are always limited to the trailing 30 days — these params can narrow that window but can't widen it beyond 30 days back. They filter against `lastAttempt` (when that specific delivery attempt happened), not `createdOn` (when the underlying event was first created) — the two can differ for retried deliveries.
|
|
781
|
+
|
|
782
|
+
```
|
|
783
|
+
GET /webhook/logs/?start_date=2026-07-20&end_date=2026-07-25
|
|
784
|
+
```
|
|
785
|
+
|
|
786
|
+
```
|
|
787
|
+
GET /orders/?billing_type=SUBSCRIPTION&is_renewal=false
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
</Update>
|
|
791
|
+
|
|
792
|
+
<Update label="v1.6.0" description="July 29, 2026" tags={["API"]}>
|
|
793
|
+
|
|
794
|
+
### New Features
|
|
795
|
+
|
|
796
|
+
#### Filter subscriptions by status
|
|
797
|
+
|
|
798
|
+
`GET /subscriptions/` now accepts a `status` query parameter. Pass a comma-separated list to match any of several statuses, e.g. `?status=active,trialing`.
|
|
799
|
+
|
|
800
|
+
```
|
|
801
|
+
GET /subscriptions/?status=active,trialing
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
This changes the shape of the response compared to the default (no `status`) call:
|
|
805
|
+
|
|
806
|
+
- **Without `status`**: exactly one row per subscription — its most recent state, with expired (`end_date` in the past) and superseded records excluded.
|
|
807
|
+
- **With `status`**: that deduplication and exclusion is skipped, and matching records are returned directly. A subscription that has passed through the requested status more than once, or whose only matching record has since expired or been superseded, can appear more than once or in a state you didn't expect.
|
|
808
|
+
|
|
809
|
+
Use `status` for point-in-time queries ("show me everything currently `active`"); omit it for the current, deduplicated view of each subscription.
|
|
810
|
+
|
|
811
|
+
### Fixes
|
|
812
|
+
|
|
813
|
+
#### HTTPS pagination links
|
|
814
|
+
|
|
815
|
+
Paginated list responses' `next` and `previous` links now correctly use `https://` when the request was made over HTTPS. Previously they were always rendered as `http://`, regardless of the request's actual scheme.
|
|
816
|
+
|
|
817
|
+
</Update>
|
|
818
|
+
|
|
819
|
+
<Update label="v1.5.0" description="July 28, 2026" tags={["API"]}>
|
|
820
|
+
|
|
821
|
+
### Changes
|
|
822
|
+
|
|
823
|
+
#### Itemized Merchant of Record fees
|
|
824
|
+
|
|
825
|
+
Transaction responses from `GET /transaction/` now include `morFeeBreakdown`, an array that itemizes the Merchant of Record fee charged for the transaction.
|
|
826
|
+
|
|
827
|
+
Each component includes its `name`, percentage rate, amount in minor units (`valueUnits`), and currency. Fixed fees return `null` for `percentage`. Transactions without an applicable Merchant of Record fee return an empty array.
|
|
828
|
+
|
|
829
|
+
```json
|
|
830
|
+
{
|
|
831
|
+
"morFee": 4,
|
|
832
|
+
"morFeeBreakdown": [
|
|
833
|
+
{
|
|
834
|
+
"name": "fixed_fee",
|
|
835
|
+
"percentage": null,
|
|
836
|
+
"valueUnits": 40,
|
|
837
|
+
"currency": "USD"
|
|
838
|
+
},
|
|
839
|
+
{
|
|
840
|
+
"name": "base_fee",
|
|
841
|
+
"percentage": "2.9",
|
|
842
|
+
"valueUnits": 290,
|
|
843
|
+
"currency": "USD"
|
|
844
|
+
},
|
|
845
|
+
{
|
|
846
|
+
"name": "subscription_fee",
|
|
847
|
+
"percentage": "0.7",
|
|
848
|
+
"valueUnits": 70,
|
|
849
|
+
"currency": "USD"
|
|
850
|
+
}
|
|
851
|
+
]
|
|
852
|
+
}
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
Possible components are `base_fee`, `fixed_fee`, `international_fee`, `subscription_fee`, and `conversion_fee`. A `fee_adjustment` component (also `null` percentage) is included when the calculated fee is raised to match a processor-fee floor.
|
|
856
|
+
|
|
857
|
+
</Update>
|
|
858
|
+
|
|
859
|
+
<Update label="v1.14" description="July 24, 2026" tags={["App"]}>
|
|
860
|
+
|
|
861
|
+
## Meet the Kelviq CLI (beta)
|
|
862
|
+
|
|
863
|
+
You can now manage your pricing catalog as code. The Kelviq CLI (`@kelviq/cli`) turns your products, features, plans, entitlements, and prices into one typed TypeScript file, `kelviq.config.ts`, that lives in your repository like the rest of your code.
|
|
864
|
+
|
|
865
|
+
The loop works in both directions:
|
|
866
|
+
|
|
867
|
+
* `kelviq pull` writes your live catalog to a config file, so a catalog you built in the dashboard is one command away from version control.
|
|
868
|
+
* `kelviq push` deploys the file back. It shows a diff, asks for confirmation, and writes drafts first. Nothing a customer sees changes until you pass `--publish`, which asks again.
|
|
869
|
+
* `kelviq promote` moves your whole sandbox catalog to production with the same preview and gates.
|
|
870
|
+
|
|
871
|
+
Your pricing model decides what customers are billed and which features they can reach, but dashboard edits leave no trail in your engineering workflow. With the catalog in git, every pricing change is a commit with an author, a diff, and a pull-request review. Drift between sandbox and production stops being invisible too: pull both environments and `diff` the two files.
|
|
872
|
+
|
|
873
|
+
Because the config is plain TypeScript, your editor autocompletes it and the compiler catches mistakes. A misspelled field or an invalid enum fails with a "did you mean" suggestion before Kelviq ever sees it. It also gives AI coding assistants something they are good at working with: ask one to "add a Team plan between Pro and Enterprise with 25 seats" and the types keep it honest.
|
|
874
|
+
|
|
875
|
+
Install it with `npm install -g @kelviq/cli`, run `kelviq login`, then `kelviq pull`. The CLI is in beta. It is safe by design, with previews and confirmations before every write, but commands and flags may still change between releases, so pin an exact version in CI. Start with the [CLI overview](/cli/overview).
|
|
876
|
+
|
|
877
|
+
## A bigger, safer MCP server
|
|
878
|
+
|
|
879
|
+
Two releases of `@kelviq/mcp-server` shipped this week for teams driving Kelviq from Claude, Cursor, or any other MCP client.
|
|
880
|
+
|
|
881
|
+
**v0.3.0** adds sandbox support. Set `KELVIQ_ENV=sandbox` and the server targets your sandbox API hosts automatically; an invalid value fails fast at startup instead of silently hitting production. `portal_session_create` now returns a ready-to-share `signedPortalUrl` with the session token already appended, since the bare portal URL does not authenticate on its own.
|
|
882
|
+
|
|
883
|
+
**v0.4.0** completes the checkout surface. `checkout_create_session` now accepts every field the API supports, including `customAmount` for custom-priced sessions, `discountCode`, and `metadata`. Fields the server did not recognize were previously dropped before the request was sent; a spec-conformance suite now guards every request schema against the OpenAPI spec so that cannot happen again.
|
|
884
|
+
|
|
885
|
+
All 45 tools now declare MCP safety annotations, so clients can auto-approve read-only calls while asking for confirmation on destructive ones like `subscription_cancel`. Three guided prompts encode common workflows end to end: `setup_product`, `launch_plan`, and `diagnose_customer`. In Claude Code they appear as slash commands, such as `/kelviq:setup_product`.
|
|
886
|
+
|
|
887
|
+
Six write tools were removed in v0.3.0, including bulk price editing, which now belongs to the CLI's reviewed `kelviq push` flow. The full list of changes is in the [MCP server changelog](/changelog#mcp-server), and the [MCP server guide](/guides/mcp-server) covers setup.
|
|
888
|
+
|
|
889
|
+
</Update>
|
|
890
|
+
|
|
891
|
+
<Update label="v0.4.0" description="July 24, 2026" tags={["MCP Server"]}>
|
|
892
|
+
|
|
893
|
+
### New Features
|
|
894
|
+
|
|
895
|
+
#### Full checkout surface
|
|
896
|
+
|
|
897
|
+
`checkout_create_session` now accepts every field the API supports — including `customAmount` (with `taxBehavior` and `currencyCode`) for custom-priced sessions, `discountCode` to pre-apply a coupon, `metadata` (returned verbatim on the `checkout.completed` webhook), `discountsEnabled`, `lockEmail`, and `defaultBillingCountry`. Previously these were silently dropped before the request was sent.
|
|
898
|
+
|
|
899
|
+
#### Subscription update options
|
|
900
|
+
|
|
901
|
+
`subscription_update` now supports `trialEnd` (`"now"` or an ISO 8601 datetime) and `paymentBehavior: "activate_on_payment"` to keep the current subscription active until payment for the update succeeds.
|
|
902
|
+
|
|
903
|
+
#### Safety annotations on every tool
|
|
904
|
+
|
|
905
|
+
All 45 tools now declare [MCP tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) — `readOnlyHint`, `destructiveHint`, `idempotentHint` — so MCP clients can auto-approve reads while asking for confirmation on destructive operations like `plan_archive` or `subscription_cancel`.
|
|
906
|
+
|
|
907
|
+
#### Guided prompts
|
|
908
|
+
|
|
909
|
+
Three built-in MCP prompts encode the golden-path workflows: `setup_product` (catalog bootstrap end-to-end), `launch_plan` (add a plan to an existing product), and `diagnose_customer` (entitlement/subscription cross-check). In Claude Code they appear as slash commands, e.g. `/kelviq:setup_product`.
|
|
910
|
+
|
|
911
|
+
### Fixes
|
|
912
|
+
|
|
913
|
+
- The server now reports its real version to MCP clients (it was pinned to an old value).
|
|
914
|
+
- An automated spec-conformance suite now guards every request schema against the OpenAPI spec, so new API fields can no longer be silently dropped.
|
|
915
|
+
|
|
916
|
+
</Update>
|
|
917
|
+
|
|
918
|
+
<Update label="v0.3.0" description="July 24, 2026" tags={["MCP Server"]}>
|
|
919
|
+
|
|
920
|
+
### New Features
|
|
921
|
+
|
|
922
|
+
#### Sandbox environment support
|
|
923
|
+
|
|
924
|
+
Set `KELVIQ_ENV=sandbox` to target your sandbox environment — the server switches both API hosts (`sandboxapi.kelviq.com` and `edge.sandboxapi.kelviq.com`) automatically. Keys only work against their own environment, and an invalid `KELVIQ_ENV` value fails fast at startup instead of silently hitting production.
|
|
925
|
+
|
|
926
|
+
#### Signed portal links
|
|
927
|
+
|
|
928
|
+
`portal_session_create` now returns a ready-to-share `signedPortalUrl` — the portal URL with the session token already appended. The bare `customerPortalUrl` does not authenticate on its own; always share the signed link.
|
|
929
|
+
|
|
930
|
+
### Breaking Changes
|
|
931
|
+
|
|
932
|
+
Six tools were removed: `media_presigned_upload`, the four `partner_org_*` tools, and `plan_prices_bulk_set`. Plan pricing is managed in the dashboard or with the [Kelviq CLI](/cli/overview) (`kelviq push`), which previews and confirms every price change; `plan_prices_list` (read) remains available.
|
|
933
|
+
|
|
934
|
+
### Improvements
|
|
935
|
+
|
|
936
|
+
- `subscription_create` now documents that it requires off-session charging to be enabled for your organization, with `checkout_create_session` as the fallback.
|
|
937
|
+
- The missing-key error links directly to the API-keys page in the right dashboard mode for your environment.
|
|
938
|
+
|
|
939
|
+
</Update>
|
|
940
|
+
|
|
941
|
+
<Update label="v2.7.3" description="July 21, 2026" tags={["Node SDK"]}>
|
|
942
|
+
|
|
943
|
+
### New Features
|
|
944
|
+
|
|
945
|
+
#### Activate Subscription Updates After Payment
|
|
946
|
+
|
|
947
|
+
`client.subscriptions.update()` now supports `paymentBehavior`. Use the exported `PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT` constant to keep the current subscription active until payment for the update succeeds.
|
|
948
|
+
|
|
949
|
+
```typescript
|
|
950
|
+
import { CHARGE_PERIOD_CHOICES, PAYMENT_BEHAVIORS } from "@kelviq/node-sdk";
|
|
951
|
+
|
|
952
|
+
const subscription = await client.subscriptions.update({
|
|
953
|
+
subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
954
|
+
planIdentifier: "premium-plan",
|
|
955
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
956
|
+
paymentBehavior: PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT,
|
|
957
|
+
});
|
|
958
|
+
```
|
|
959
|
+
|
|
960
|
+
The SDK serializes the option as `payment_behavior: "activate_on_payment"`. If payment is not completed and the pending update expires, the existing subscription remains active and unchanged.
|
|
961
|
+
|
|
962
|
+
</Update>
|
|
963
|
+
|
|
964
|
+
<Update label="v2.7.3" description="July 21, 2026" tags={["Python SDK"]}>
|
|
965
|
+
|
|
966
|
+
### New Features
|
|
967
|
+
|
|
968
|
+
#### Activate Subscription Updates After Payment
|
|
969
|
+
|
|
970
|
+
The synchronous and asynchronous `client.subscriptions.update()` methods now support `paymentBehavior="activate_on_payment"`. This keeps the current subscription active while payment for the update is pending.
|
|
971
|
+
|
|
972
|
+
```python
|
|
973
|
+
subscription = client.subscriptions.update(
|
|
974
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
975
|
+
planIdentifier="premium-plan",
|
|
976
|
+
chargePeriod="MONTHLY",
|
|
977
|
+
paymentBehavior="activate_on_payment",
|
|
978
|
+
)
|
|
979
|
+
```
|
|
980
|
+
|
|
981
|
+
The SDK validates the option and serializes it as `payment_behavior`. The new plan and features are applied only after payment succeeds; if the pending update expires, the existing subscription remains active and unchanged.
|
|
982
|
+
|
|
983
|
+
</Update>
|
|
984
|
+
|
|
985
|
+
<Update label="v1.13" description="July 17, 2026" tags={["App"]}>
|
|
986
|
+
|
|
987
|
+
## Safer discount creation
|
|
988
|
+
|
|
989
|
+
Fixed-amount discounts now include an explicit currency selector. Kelviq places the currency from your organization profile first in the selector, while still letting you review and choose the currency for the discount.
|
|
990
|
+
|
|
991
|
+
Discount validation is also more reliable:
|
|
992
|
+
|
|
993
|
+
* Kelviq shows an error when a fixed-amount discount's currency does not match the selected price.
|
|
994
|
+
* Product-restricted discounts now use stricter product-selection validation during creation.
|
|
995
|
+
* Recurring discounts are now enabled by default, matching the behavior many users expected. You can still limit a discount to a fixed number of billing cycles or let it apply forever.
|
|
996
|
+
* Fixed a bug that moved the cursor to the end of a discount field while typing.
|
|
997
|
+
|
|
998
|
+
## Trials now follow the selected billing model
|
|
999
|
+
|
|
1000
|
+
Trials are available only when a plan has at least one recurring price. One-time-only plans no longer expose trial settings or show a trial at checkout.
|
|
1001
|
+
|
|
1002
|
+
If a plan starts with both recurring and one-time pricing and the final recurring price is later disabled, Kelviq now removes the trial behavior from the remaining one-time offer.
|
|
1003
|
+
|
|
1004
|
+
## Resend webhook deliveries from the dashboard
|
|
1005
|
+
|
|
1006
|
+
Webhook delivery logs now include a **Resend** action. If a delivery fails because an endpoint is unavailable or returns an error, you can fix the endpoint and retry the delivery from the Kelviq dashboard.
|
|
1007
|
+
|
|
1008
|
+
The new attempt appears in the delivery logs, where you can inspect its status and response without waiting for another event.
|
|
1009
|
+
|
|
1010
|
+
A resend can deliver the same event more than once. Webhook handlers should use the event `id` or `webhook-id` header as an idempotency key.
|
|
1011
|
+
|
|
1012
|
+
## Faster feature selection
|
|
1013
|
+
|
|
1014
|
+
After a feature is added from the **Manage features & limits** dialog, Kelviq now clears the search field. You can immediately search for and add another feature without deleting the previous query.
|
|
1015
|
+
|
|
1016
|
+
## Customer portal fixes
|
|
1017
|
+
|
|
1018
|
+
We fixed two customer portal edge cases:
|
|
1019
|
+
|
|
1020
|
+
* Login code input is normalized to uppercase as the customer types.
|
|
1021
|
+
* The cancel action remains available for an active subscription when an associated order has been refunded.
|
|
1022
|
+
|
|
1023
|
+
</Update>
|
|
1024
|
+
|
|
1025
|
+
<Update label="v1.4.0" description="July 17, 2026" tags={["API"]}>
|
|
1026
|
+
|
|
1027
|
+
### New Features
|
|
1028
|
+
|
|
1029
|
+
#### 28-day subscription billing
|
|
1030
|
+
|
|
1031
|
+
Checkout and subscription creation now support a four-week billing period. Pass `TWENTY_EIGHT_DAYS` as `chargePeriod` when creating an eligible checkout session or subscription.
|
|
1032
|
+
|
|
1033
|
+
This is useful for products sold in fixed four-week cycles: renewals happen on the same weekday every four weeks, and metered usage can reset on the same schedule instead of following calendar months.
|
|
1034
|
+
|
|
1035
|
+
```json
|
|
1036
|
+
{
|
|
1037
|
+
"planIdentifier": "four-week-pro",
|
|
1038
|
+
"chargePeriod": "TWENTY_EIGHT_DAYS",
|
|
1039
|
+
"customerId": "customer_123",
|
|
1040
|
+
"successUrl": "https://app.example.com/billing/success"
|
|
1041
|
+
}
|
|
1042
|
+
```
|
|
1043
|
+
|
|
1044
|
+
Metered features that follow the same cadence can use `EVERY_28_DAYS` as their usage reset period.
|
|
1045
|
+
|
|
1046
|
+
The new billing period works across renewals, orders, invoices, emails, and subscription reporting. Organizations must enable the 28-day period before using it on a plan.
|
|
1047
|
+
|
|
1048
|
+
#### Subscription end dates in webhook payloads
|
|
1049
|
+
|
|
1050
|
+
Subscription webhook payloads now include `end_date` inside `data.object`. The field contains an ISO 8601 date when the subscription has a known end date and `null` when no end date is set.
|
|
1051
|
+
|
|
1052
|
+
```json
|
|
1053
|
+
{
|
|
1054
|
+
"type": "subscription.cancelled",
|
|
1055
|
+
"data": {
|
|
1056
|
+
"object": {
|
|
1057
|
+
"id": "sub_123",
|
|
1058
|
+
"end_date": "2026-08-17"
|
|
1059
|
+
}
|
|
1060
|
+
}
|
|
1061
|
+
}
|
|
1062
|
+
```
|
|
1063
|
+
|
|
1064
|
+
Merchants can use this value to schedule access removal, customer notifications, and account cleanup without making a separate request for the latest subscription.
|
|
1065
|
+
|
|
1066
|
+
### Fixes
|
|
1067
|
+
|
|
1068
|
+
#### Reliable `invoice.paid` webhook delivery
|
|
1069
|
+
|
|
1070
|
+
Kelviq now emits `invoice.paid` when an invoice is created with a `PAID` status. Previously, these invoices could emit only `invoice.created`, which meant integrations waiting for `invoice.paid` did not receive confirmation that payment had been collected.
|
|
1071
|
+
|
|
1072
|
+
The event payload has not changed. Continue to use `data.object.status`, `data.object.paid_at`, and `data.object.subscription_id` when processing the event.
|
|
1073
|
+
|
|
1074
|
+
</Update>
|
|
1075
|
+
|
|
1076
|
+
<Update label="v1.3.1" description="July 17, 2026" tags={["API"]}>
|
|
1077
|
+
|
|
1078
|
+
### Changes
|
|
1079
|
+
|
|
1080
|
+
#### Multiple customers can use the same email
|
|
1081
|
+
|
|
1082
|
+
More than one customer record can now use the same email address. This removes the previous one-customer-per-email restriction.
|
|
1083
|
+
|
|
1084
|
+
Each record must still have a unique `customerId`. Archiving a customer does not release that ID, so it cannot be assigned to a new record.
|
|
1085
|
+
|
|
1086
|
+
</Update>
|
|
1087
|
+
|
|
1088
|
+
<Update label="v1.3.0" description="July 16, 2026" tags={["API"]}>
|
|
1089
|
+
|
|
1090
|
+
### New Features
|
|
1091
|
+
|
|
1092
|
+
#### List, Create, and Retrieve Refunds
|
|
1093
|
+
|
|
1094
|
+
The Refunds API now supports the complete refund workflow:
|
|
1095
|
+
|
|
1096
|
+
- **`GET /refunds/` — List refunds**: Returns a paginated list of refunds for the authenticated organization, with search, status, date-range, and pagination filters.
|
|
1097
|
+
- **`POST /refunds/` — Create a refund**: Creates a full or partial refund for an order. Provide `amountUnits` or `amount` for a partial refund, or omit both to refund the remaining balance.
|
|
1098
|
+
- **`GET /refunds/{refundId}/` — Retrieve a refund**: Returns a refund by its Kelviq UUID.
|
|
1099
|
+
|
|
1100
|
+
Create requests use `orderId` to identify the order. List results, newly created refunds, and retrieved refunds share the same response format, including the refund amount, reason, status, failure details, internal note, and associated order.
|
|
1101
|
+
|
|
1102
|
+
</Update>
|
|
1103
|
+
|
|
1104
|
+
<Update label="v2.7.2" description="July 14, 2026" tags={["Node SDK"]}>
|
|
1105
|
+
|
|
1106
|
+
### New Features
|
|
1107
|
+
|
|
1108
|
+
#### List, Retrieve, and Create Subscriptions
|
|
1109
|
+
|
|
1110
|
+
The subscriptions module now supports the complete read and create workflow:
|
|
1111
|
+
|
|
1112
|
+
- `client.subscriptions.list()` retrieves a customer's paginated subscription list with optional pagination controls.
|
|
1113
|
+
- `client.subscriptions.retrieve()` retrieves a subscription by its Kelviq UUID.
|
|
1114
|
+
- `client.subscriptions.create()` creates a subscription directly for a customer.
|
|
1115
|
+
|
|
1116
|
+
```typescript
|
|
1117
|
+
const page = await client.subscriptions.list({
|
|
1118
|
+
customerId: "cust_789",
|
|
1119
|
+
page: 1,
|
|
1120
|
+
pageSize: 20,
|
|
1121
|
+
});
|
|
1122
|
+
|
|
1123
|
+
const subscription = await client.subscriptions.retrieve({
|
|
1124
|
+
subscriptionId: page.results[0].id,
|
|
1125
|
+
});
|
|
1126
|
+
|
|
1127
|
+
const created = await client.subscriptions.create({
|
|
1128
|
+
planIdentifier: "plan-pro-monthly",
|
|
1129
|
+
chargePeriod: "MONTHLY",
|
|
1130
|
+
customerId: "cust_789",
|
|
1131
|
+
});
|
|
1132
|
+
```
|
|
1133
|
+
|
|
1134
|
+
New TypeScript models cover paginated results, create payloads, product and plan details, features, files, links, and issued licenses.
|
|
1135
|
+
|
|
1136
|
+
</Update>
|
|
1137
|
+
|
|
1138
|
+
<Update label="v2.7.2" description="July 14, 2026" tags={["Python SDK"]}>
|
|
1139
|
+
|
|
1140
|
+
### New Features
|
|
1141
|
+
|
|
1142
|
+
#### List, Retrieve, and Create Subscriptions
|
|
1143
|
+
|
|
1144
|
+
The synchronous and asynchronous subscription clients now support the complete read and create workflow:
|
|
1145
|
+
|
|
1146
|
+
- `client.subscriptions.list()` retrieves a customer's paginated subscription list with optional pagination controls.
|
|
1147
|
+
- `client.subscriptions.retrieve()` retrieves a subscription by its Kelviq UUID.
|
|
1148
|
+
- `client.subscriptions.create()` creates a subscription directly for a customer.
|
|
1149
|
+
|
|
1150
|
+
```python
|
|
1151
|
+
page = client.subscriptions.list(
|
|
1152
|
+
customerId="cust_789",
|
|
1153
|
+
page=1,
|
|
1154
|
+
page_size=20,
|
|
1155
|
+
)
|
|
1156
|
+
|
|
1157
|
+
subscription = client.subscriptions.retrieve(
|
|
1158
|
+
subscriptionId=page.results[0].id,
|
|
1159
|
+
)
|
|
1160
|
+
|
|
1161
|
+
created = client.subscriptions.create(
|
|
1162
|
+
planIdentifier="plan-pro-monthly",
|
|
1163
|
+
chargePeriod="MONTHLY",
|
|
1164
|
+
customerId="cust_789",
|
|
1165
|
+
)
|
|
1166
|
+
```
|
|
1167
|
+
|
|
1168
|
+
All three methods are also available on `async_client` and return validated Pydantic models. New models cover paginated results, create payloads, product and plan details, features, files, links, and issued licenses.
|
|
1169
|
+
|
|
1170
|
+
</Update>
|
|
1171
|
+
|
|
1172
|
+
<Update label="v1.2.0" description="July 14, 2026" tags={["API"]}>
|
|
1173
|
+
|
|
1174
|
+
### New Features
|
|
1175
|
+
|
|
1176
|
+
#### Subscription List, Create, and Retrieve APIs
|
|
1177
|
+
|
|
1178
|
+
The Subscriptions API now includes three new endpoints for reading and creating subscriptions:
|
|
1179
|
+
|
|
1180
|
+
- **`GET /subscriptions/` — List subscriptions**: Retrieves a paginated list for a customer. The `customer_id` query parameter is required.
|
|
1181
|
+
- **`POST /subscriptions/create/` — Create a subscription**: Creates a subscription directly for a customer without requiring a checkout session.
|
|
1182
|
+
- **`GET /subscriptions/{subscriptionId}/` — Retrieve a subscription**: Retrieves a subscription by its Kelviq UUID.
|
|
1183
|
+
|
|
1184
|
+
Subscription list, create, and retrieve responses now include:
|
|
1185
|
+
|
|
1186
|
+
- `files` — downloadable files attached to the subscription's plan.
|
|
1187
|
+
- `links` — external links attached to the plan.
|
|
1188
|
+
- `license` — issued licenses associated with the subscription.
|
|
1189
|
+
|
|
1190
|
+
#### One-Time Charges
|
|
1191
|
+
|
|
1192
|
+
The new `POST /charges/` endpoint immediately charges a customer's saved payment method without creating a checkout session. The `chargePeriod` must be `ONE_TIME`.
|
|
1193
|
+
|
|
1194
|
+
</Update>
|
|
1195
|
+
|
|
1196
|
+
<Update label="v1.12" description="July 10, 2026" tags={["App"]}>
|
|
1197
|
+
|
|
1198
|
+
## Customer deliverables in one place
|
|
1199
|
+
|
|
1200
|
+
Customer detail pages now include the files, links, and license keys delivered through a customer's plans. Support teams can review a customer's access and manage license keys without opening the related order first.
|
|
1201
|
+
|
|
1202
|
+
This makes common support requests faster, including:
|
|
1203
|
+
|
|
1204
|
+
* Finding a purchased download
|
|
1205
|
+
* Opening a private resource link
|
|
1206
|
+
* Reviewing an issued license key
|
|
1207
|
+
* Managing a customer's license access
|
|
1208
|
+
|
|
1209
|
+
## Better feature and usage configuration
|
|
1210
|
+
|
|
1211
|
+
We improved the feature-management experience for metered and configurable entitlements:
|
|
1212
|
+
|
|
1213
|
+
* Numeric values now use number inputs where appropriate.
|
|
1214
|
+
* Credit rollover appears before usage alerts, matching the order in which these settings are configured.
|
|
1215
|
+
* Feature names can be edited from the feature row's action menu.
|
|
1216
|
+
* Regional prices now carry over the base price's usage reset, usage alert, and credit rollover settings.
|
|
1217
|
+
|
|
1218
|
+
These changes reduce repetitive setup and keep entitlement behavior consistent across base and regional prices.
|
|
1219
|
+
|
|
1220
|
+
## Business details are easier to find
|
|
1221
|
+
|
|
1222
|
+
Business verification is now available from **Settings → Business details** as well as the onboarding flow. Kelviq also uses the country from the organization profile to make the relevant country option easier to find during verification.
|
|
1223
|
+
|
|
1224
|
+
## Cleaner catalog, settings, and sandbox navigation
|
|
1225
|
+
|
|
1226
|
+
We simplified several dashboard workflows:
|
|
1227
|
+
|
|
1228
|
+
* Product identifiers are no longer shown or requested in the product interface. Kelviq uses the product's internal UUID.
|
|
1229
|
+
* The sandbox no longer shows a **Start selling** action, because live selling is completed from the production environment.
|
|
1230
|
+
* Settings navigation has clearer visual separation between groups.
|
|
1231
|
+
|
|
1232
|
+
</Update>
|
|
1233
|
+
|
|
1234
|
+
<Update label="v2.7.0-beta.2" description="July 10, 2026" tags={["Node SDK"]}>
|
|
1235
|
+
|
|
1236
|
+
### New Features
|
|
1237
|
+
|
|
1238
|
+
#### Create One-Time Charges
|
|
1239
|
+
|
|
1240
|
+
A new `client.charges.create()` method can immediately charge a customer's saved payment method without creating a checkout session.
|
|
1241
|
+
|
|
1242
|
+
```typescript
|
|
1243
|
+
const charge = await client.charges.create({
|
|
1244
|
+
planIdentifier: "lifetime-access",
|
|
1245
|
+
chargePeriod: "ONE_TIME",
|
|
1246
|
+
customerId: "cust_789",
|
|
1247
|
+
currencyCode: "USD",
|
|
1248
|
+
features: [{ identifier: "seats", quantity: 5 }],
|
|
1249
|
+
ipAddress: "103.154.35.20",
|
|
1250
|
+
});
|
|
1251
|
+
|
|
1252
|
+
console.log(charge.id, charge.status, charge.amount);
|
|
1253
|
+
```
|
|
1254
|
+
|
|
1255
|
+
The customer must already have a usable payment method on file. `chargePeriod` is restricted to `"ONE_TIME"`; use the subscriptions API for recurring billing. The SDK includes typed request and response models for charge records.
|
|
1256
|
+
|
|
1257
|
+
</Update>
|
|
1258
|
+
|
|
1259
|
+
<Update label="v2.7.1" description="July 10, 2026" tags={["Python SDK"]}>
|
|
1260
|
+
|
|
1261
|
+
### New Features
|
|
1262
|
+
|
|
1263
|
+
#### Create One-Time Charges
|
|
1264
|
+
|
|
1265
|
+
The synchronous and asynchronous clients now provide `client.charges.create()` for immediately charging a customer's saved payment method without creating a checkout session.
|
|
1266
|
+
|
|
1267
|
+
```python
|
|
1268
|
+
charge = client.charges.create(
|
|
1269
|
+
planIdentifier="lifetime-access",
|
|
1270
|
+
chargePeriod="ONE_TIME",
|
|
1271
|
+
customerId="cust_789",
|
|
1272
|
+
currencyCode="USD",
|
|
1273
|
+
features=[{"identifier": "seats", "quantity": 5}],
|
|
1274
|
+
ipAddress="103.154.35.20",
|
|
1275
|
+
)
|
|
1276
|
+
|
|
1277
|
+
print(charge.id, charge.status, charge.amount)
|
|
1278
|
+
```
|
|
1279
|
+
|
|
1280
|
+
**Async variant:**
|
|
1281
|
+
|
|
1282
|
+
```python
|
|
1283
|
+
charge = await async_client.charges.create(
|
|
1284
|
+
planIdentifier="lifetime-access",
|
|
1285
|
+
chargePeriod="ONE_TIME",
|
|
1286
|
+
customerId="cust_789",
|
|
1287
|
+
)
|
|
1288
|
+
```
|
|
1289
|
+
|
|
1290
|
+
The customer must already have a usable payment method on file. `chargePeriod` is restricted to `"ONE_TIME"`; use the subscriptions API for recurring billing. Pydantic request and response models validate parameters and provide typed charge records.
|
|
1291
|
+
|
|
1292
|
+
</Update>
|
|
1293
|
+
|
|
1294
|
+
<Update label="v2.7.0" description="July 4, 2026" tags={["Node SDK"]}>
|
|
1295
|
+
|
|
1296
|
+
### New Features
|
|
1297
|
+
|
|
1298
|
+
#### Caching & Offline Resilience
|
|
1299
|
+
|
|
1300
|
+
The SDK now includes a two-tier cache that keeps entitlement checks fast and lets your app keep working during transient network/API outages.
|
|
1301
|
+
|
|
1302
|
+
- **L1 — in-memory** (on by default): entitlements are cached per-process. Fresh entries (within the TTL) are served without a network call; if the API is unreachable or returns a 5xx, the last-known value is served as a fallback.
|
|
1303
|
+
- **L2 — distributed** (optional): a shared store (e.g. Redis) so the cache and the offline usage queue are shared across processes and containers, and survive restarts.
|
|
1304
|
+
|
|
1305
|
+
Read-through order is **L1 → L2 → API**, with write-through to both on every successful fetch.
|
|
1306
|
+
|
|
1307
|
+
```typescript
|
|
1308
|
+
const client = new Kelviq({
|
|
1309
|
+
accessToken: process.env.KELVIQ_API_KEY,
|
|
1310
|
+
enableCache: true, // default true
|
|
1311
|
+
cacheTtlMs: 60_000, // freshness window in ms (default 60000)
|
|
1312
|
+
});
|
|
1313
|
+
```
|
|
1314
|
+
|
|
1315
|
+
Set `enableCache: false` to disable caching entirely.
|
|
1316
|
+
|
|
1317
|
+
#### Offline Usage Queue
|
|
1318
|
+
|
|
1319
|
+
Usage/event reports that fail due to a network error are automatically **queued** and replayed on the next report call (or via `client.reporting.flush()`), so measurements are not lost during brief outages. Cached entitlement usage is updated optimistically so access checks stay consistent while offline.
|
|
1320
|
+
|
|
1321
|
+
```typescript
|
|
1322
|
+
const remaining = await client.reporting.flush(); // returns count still queued
|
|
1323
|
+
```
|
|
1324
|
+
|
|
1325
|
+
#### Distributed Cache — `RedisStore`
|
|
1326
|
+
|
|
1327
|
+
A ready-to-use `RedisStore` (backed by `ioredis`, an optional dependency) can be shared across multiple instances / containers so they use one cache and one durable usage queue.
|
|
1328
|
+
|
|
1329
|
+
```typescript
|
|
1330
|
+
import { Kelviq, RedisStore } from '@kelviq/node-sdk';
|
|
1331
|
+
|
|
1332
|
+
const store = new RedisStore({ url: 'redis://localhost:6379/0', prefix: 'kelviq:prod' });
|
|
1333
|
+
const client = new Kelviq({ accessToken: process.env.KELVIQ_API_KEY, cacheStore: store });
|
|
1334
|
+
```
|
|
1335
|
+
|
|
1336
|
+
You can also bring your own backend by implementing the public `CacheStore` interface and passing it as `cacheStore`. All instances that should share a cache must use the same `prefix`.
|
|
1337
|
+
|
|
1338
|
+
</Update>
|
|
1339
|
+
|
|
1340
|
+
<Update label="v2.7.0" description="July 4, 2026" tags={["Python SDK"]}>
|
|
1341
|
+
|
|
1342
|
+
### New Features
|
|
1343
|
+
|
|
1344
|
+
#### Caching & Offline Resilience
|
|
1345
|
+
|
|
1346
|
+
The SDK now includes a two-tier cache that keeps entitlement checks fast and lets your app keep working during transient network/API outages.
|
|
1347
|
+
|
|
1348
|
+
- **L1 — in-memory** (on by default): entitlements are cached per-process. Fresh entries (within the TTL) are served without a network call; if the API is unreachable or returns a 5xx, the last-known value is served as a fallback.
|
|
1349
|
+
- **L2 — distributed** (optional): a shared store (e.g. Redis) so the cache and the offline usage queue are shared across processes / gunicorn workers / containers, and survive restarts.
|
|
1350
|
+
|
|
1351
|
+
Read-through order is **L1 → L2 → API**, with write-through to both on every successful fetch.
|
|
1352
|
+
|
|
1353
|
+
```python
|
|
1354
|
+
client = Kelviq.create_sync_client(
|
|
1355
|
+
access_token=ACCESS_TOKEN,
|
|
1356
|
+
enable_cache=True, # default True
|
|
1357
|
+
cache_ttl=60.0, # freshness window in seconds (default 60)
|
|
1358
|
+
)
|
|
1359
|
+
```
|
|
1360
|
+
|
|
1361
|
+
Set `enable_cache=False` to disable caching entirely. Both the sync and async clients are supported.
|
|
1362
|
+
|
|
1363
|
+
#### Offline Usage Queue
|
|
1364
|
+
|
|
1365
|
+
Usage/event reports that fail due to a network error are automatically **queued** and replayed on the next report call (or via `client.reporting.flush()`), so measurements are not lost during brief outages. Cached entitlement usage is updated optimistically so access checks stay consistent while offline.
|
|
1366
|
+
|
|
1367
|
+
```python
|
|
1368
|
+
remaining = client.reporting.flush() # returns count still queued
|
|
1369
|
+
# async: remaining = await async_client.reporting.flush()
|
|
1370
|
+
```
|
|
1371
|
+
|
|
1372
|
+
#### Distributed Cache — `RedisStore` / `AsyncRedisStore`
|
|
1373
|
+
|
|
1374
|
+
Ready-to-use Redis-backed stores can be shared across multiple processes / gunicorn workers / containers so they use one cache and one durable usage queue. Redis is an optional extra (`pip install "kelviq-sdk[redis]"`).
|
|
1375
|
+
|
|
1376
|
+
```python
|
|
1377
|
+
from kelviq_sdk import Kelviq, RedisStore
|
|
1378
|
+
|
|
1379
|
+
store = RedisStore(url="redis://localhost:6379/0", prefix="kelviq:prod")
|
|
1380
|
+
client = Kelviq.create_sync_client(access_token=ACCESS_TOKEN, cache_store=store)
|
|
1381
|
+
```
|
|
1382
|
+
|
|
1383
|
+
```python
|
|
1384
|
+
# Async
|
|
1385
|
+
from kelviq_sdk import Kelviq, AsyncRedisStore
|
|
1386
|
+
|
|
1387
|
+
store = AsyncRedisStore(url="redis://localhost:6379/0", prefix="kelviq:prod")
|
|
1388
|
+
async_client = Kelviq.create_async_client(access_token=ACCESS_TOKEN, cache_store=store)
|
|
1389
|
+
```
|
|
1390
|
+
|
|
1391
|
+
You can also bring your own backend by implementing the public `CacheStore` interface and passing it as `cache_store`. All workers/tasks that should share a cache must use the same `prefix`.
|
|
1392
|
+
|
|
1393
|
+
</Update>
|
|
1394
|
+
|
|
1395
|
+
<Update label="v1.11" description="June 26, 2026" tags={["App"]}>
|
|
1396
|
+
|
|
1397
|
+

|
|
1398
|
+
|
|
1399
|
+
## Quarterly billing periods
|
|
1400
|
+
|
|
1401
|
+
Kelviq now supports quarterly billing periods. Sellers can now offer plans that renew every 3 months.
|
|
1402
|
+
|
|
1403
|
+
Example pricing:
|
|
1404
|
+
|
|
1405
|
+
```text
|
|
1406
|
+
Monthly: $29 per month
|
|
1407
|
+
Quarterly: $79 per quarter
|
|
1408
|
+
Annual: $299 per year
|
|
1409
|
+
```
|
|
1410
|
+
|
|
1411
|
+
Quarterly billing is useful when monthly feels too short and annual feels too expensive. It works well for:
|
|
1412
|
+
|
|
1413
|
+
- AI tools
|
|
1414
|
+
- Developer tools
|
|
1415
|
+
- Creator products
|
|
1416
|
+
- Small business SaaS
|
|
1417
|
+
- B2B products with longer buying cycles
|
|
1418
|
+
|
|
1419
|
+
## Pay as you go improvements
|
|
1420
|
+
|
|
1421
|
+
We improved pay as you go support across the product. This makes it easier to set up and review usage based billing.
|
|
1422
|
+
|
|
1423
|
+
## Usage based pricing improvements
|
|
1424
|
+
|
|
1425
|
+
We improved the usage based pricing experience in the UI. This helps sellers create usage based plans with less confusion. Supported pricing patterns include:
|
|
1426
|
+
|
|
1427
|
+
- Per unit pricing
|
|
1428
|
+
- Package pricing
|
|
1429
|
+
- Included usage with overage
|
|
1430
|
+
- Pay as you go
|
|
1431
|
+
- Subscription plus usage
|
|
1432
|
+
- Credit based usage
|
|
1433
|
+
|
|
1434
|
+
Example:
|
|
1435
|
+
|
|
1436
|
+
```text
|
|
1437
|
+
Starter plan: $19 per month
|
|
1438
|
+
Includes: 100 AI credits
|
|
1439
|
+
Extra credits: $10 per 100 credits
|
|
1440
|
+
```
|
|
1441
|
+
|
|
1442
|
+
## Checkout pricing improvements
|
|
1443
|
+
|
|
1444
|
+
Checkout now handles more pricing cases across custom amounts, usage based plans, and tax behavior. This helps keep pricing consistent across:
|
|
1445
|
+
|
|
1446
|
+
- Pricing page
|
|
1447
|
+
- Checkout page
|
|
1448
|
+
- Customer portal
|
|
1449
|
+
- Transaction details
|
|
1450
|
+
- Invoices
|
|
1451
|
+
|
|
1452
|
+
## Node SDK webhook improvements
|
|
1453
|
+
|
|
1454
|
+
The Node SDK includes more webhook improvements for safer event handling. This helps developers build reliable flows for:
|
|
1455
|
+
|
|
1456
|
+
- License generation
|
|
1457
|
+
- Subscription access
|
|
1458
|
+
- Plan changes
|
|
1459
|
+
- Customer portal links
|
|
1460
|
+
- Usage updates
|
|
1461
|
+
- Billing state sync
|
|
1462
|
+
|
|
1463
|
+
## Final fixes and cleanup
|
|
1464
|
+
|
|
1465
|
+
We also shipped smaller fixes and cleanup across checkout, pricing, product setup, and plan setup. This includes improvements for:
|
|
1466
|
+
|
|
1467
|
+
- Checkout plan switching
|
|
1468
|
+
- Package pricing labels
|
|
1469
|
+
- Product setup flows
|
|
1470
|
+
- Plan setup flows
|
|
1471
|
+
- Checkout management
|
|
1472
|
+
- Dashboard clarity
|
|
1473
|
+
|
|
1474
|
+
</Update>
|
|
1475
|
+
|
|
1476
|
+
<Update label="v1.10" description="June 19, 2026" tags={["App"]}>
|
|
1477
|
+
|
|
1478
|
+

|
|
1479
|
+
|
|
1480
|
+
## Organization settings page
|
|
1481
|
+
|
|
1482
|
+
Kelviq now has an Organization settings page. This gives teams a central place to manage organization level settings. The goal is to keep account level setup separate from product level setup.
|
|
1483
|
+
|
|
1484
|
+
This can include:
|
|
1485
|
+
|
|
1486
|
+
- Organization name
|
|
1487
|
+
- Business details
|
|
1488
|
+
- Team settings
|
|
1489
|
+
- Billing settings
|
|
1490
|
+
- Product defaults
|
|
1491
|
+
|
|
1492
|
+
## Payout tab is visible before business verification
|
|
1493
|
+
|
|
1494
|
+
The payout tab is now visible before business verification is complete. This avoids confusion for new sellers. Before this, some users were not sure where payout setup would appear. Now sellers can see the payout area earlier, even if live payouts are not enabled yet.
|
|
1495
|
+
|
|
1496
|
+
## Zapier integration
|
|
1497
|
+
|
|
1498
|
+
Kelviq now supports Zapier integration. This helps sellers connect Kelviq with other tools without custom code.
|
|
1499
|
+
|
|
1500
|
+
Examples:
|
|
1501
|
+
|
|
1502
|
+
- Send a Slack message when a new order is created
|
|
1503
|
+
- Add a new customer to HubSpot
|
|
1504
|
+
- Create a Google Sheets row after checkout
|
|
1505
|
+
- Send an onboarding email after payment
|
|
1506
|
+
- Notify support when a refund happens
|
|
1507
|
+
- Add a buyer to a course platform
|
|
1508
|
+
|
|
1509
|
+
## Plans removed from the sidebar
|
|
1510
|
+
|
|
1511
|
+
We removed Plans from the sidebar because it was confusing. Plans are now managed inside products. This makes the dashboard easier to understand. This matches how sellers usually think about setup:
|
|
1512
|
+
|
|
1513
|
+
1. Create a product
|
|
1514
|
+
2. Add plans to the product
|
|
1515
|
+
3. Create checkout links for those plans
|
|
1516
|
+
|
|
1517
|
+
## Email removed from checkout list
|
|
1518
|
+
|
|
1519
|
+
We removed the separate email field from the checkout list because the customer column already shows the email. This makes the table cleaner and reduces repeated information.
|
|
1520
|
+
|
|
1521
|
+
## Frontend improvements
|
|
1522
|
+
|
|
1523
|
+
We shipped several dashboard improvements focused on clarity and setup speed. This includes:
|
|
1524
|
+
|
|
1525
|
+
- Cleaner product navigation
|
|
1526
|
+
- Better table layout
|
|
1527
|
+
- Better empty states
|
|
1528
|
+
- Easier checkout link access
|
|
1529
|
+
- Clearer plan setup
|
|
1530
|
+
- Better plan publishing flow
|
|
1531
|
+
|
|
1532
|
+
## Custom checkout pricing improvements
|
|
1533
|
+
|
|
1534
|
+
We improved the custom checkout pricing flow. This is useful for sales led deals and private pricing. You can create a custom checkout for that customer without adding a public plan.
|
|
1535
|
+
|
|
1536
|
+
</Update>
|
|
1537
|
+
|
|
1538
|
+
<Update label="v0.2.0 – v0.2.3" description="June 16–17, 2026" tags={["MCP Server"]}>
|
|
1539
|
+
|
|
1540
|
+
Initial public release of `@kelviq/mcp-server`: the full Kelviq API as typed MCP tools plus the entire documentation as searchable resources, followed by packaging fixes and consolidation onto a single edge host.
|
|
1541
|
+
|
|
1542
|
+
</Update>
|
|
1543
|
+
|
|
1544
|
+
<Update label="v1.9" description="June 12, 2026" tags={["App"]}>
|
|
1545
|
+
|
|
1546
|
+

|
|
1547
|
+
|
|
1548
|
+
## Subscription data in license validation
|
|
1549
|
+
|
|
1550
|
+
License checks can return subscription context along with the license result. This is important for desktop software, private model tooling, and downloadable products where access is tied to both a license key and a live subscription.
|
|
1551
|
+
|
|
1552
|
+
Example response:
|
|
1553
|
+
|
|
1554
|
+
```json
|
|
1555
|
+
{
|
|
1556
|
+
"license": {
|
|
1557
|
+
"key": "LIC-123",
|
|
1558
|
+
"status": "active"
|
|
1559
|
+
},
|
|
1560
|
+
"subscription": {
|
|
1561
|
+
"status": "active",
|
|
1562
|
+
"plan": "Pro",
|
|
1563
|
+
"trialDaysRemaining": 0
|
|
1564
|
+
...
|
|
1565
|
+
}
|
|
1566
|
+
}
|
|
1567
|
+
```
|
|
1568
|
+
|
|
1569
|
+
## License API support in the Node SDK
|
|
1570
|
+
|
|
1571
|
+
The Node SDK now supports the License API. You can validate license keys and connect license status directly to your app. Backend services using `@kelviq/node-sdk` can validate licenses without making manual API requests. For example, a CLI product can validate a license key on launch, confirm the associated subscription is active, and decide whether to unlock premium features.
|
|
1572
|
+
|
|
1573
|
+
**Example:**
|
|
1574
|
+
|
|
1575
|
+
```js
|
|
1576
|
+
const result = await client.license.validate({
|
|
1577
|
+
licenseKey: "LIC-123"
|
|
1578
|
+
});
|
|
1579
|
+
|
|
1580
|
+
if (result.valid) {
|
|
1581
|
+
// Unlock product access
|
|
1582
|
+
}
|
|
1583
|
+
```
|
|
1584
|
+
|
|
1585
|
+
This is useful for products such as:
|
|
1586
|
+
|
|
1587
|
+
* macOS apps
|
|
1588
|
+
* WordPress plugins
|
|
1589
|
+
* VS Code extensions
|
|
1590
|
+
* Figma plugins
|
|
1591
|
+
* Desktop developer tools
|
|
1592
|
+
* Paid templates
|
|
1593
|
+
|
|
1594
|
+
## Trial end support for subscription updates
|
|
1595
|
+
|
|
1596
|
+
The Node SDK now supports `trialEnd` when updating subscriptions. This gives developers more control over trials. This helps teams extend a trial after sales approval or shorten a trial when a customer upgrades early.
|
|
1597
|
+
|
|
1598
|
+
You can now handle flows like:
|
|
1599
|
+
|
|
1600
|
+
- Extend a trial by 7 days
|
|
1601
|
+
- End a trial immediately
|
|
1602
|
+
- Set a custom trial end date
|
|
1603
|
+
- Move a customer from trial to paid
|
|
1604
|
+
- Give a sales led customer a longer trial
|
|
1605
|
+
|
|
1606
|
+
```js
|
|
1607
|
+
await client.subscriptions.update({
|
|
1608
|
+
subscriptionId: "sub_123",
|
|
1609
|
+
trialEnd: "2026-06-30T23:59:59Z"
|
|
1610
|
+
});
|
|
1611
|
+
```
|
|
1612
|
+
|
|
1613
|
+
## Portal session support in the Node SDK
|
|
1614
|
+
|
|
1615
|
+
The Node SDK now supports customer portal sessions. You can create a signed portal link from your backend and send customers to the portal.
|
|
1616
|
+
|
|
1617
|
+
Example:
|
|
1618
|
+
|
|
1619
|
+
```js
|
|
1620
|
+
const session = await client.portal.createSession({
|
|
1621
|
+
customerId: "cust_789",
|
|
1622
|
+
});
|
|
1623
|
+
|
|
1624
|
+
// Redirect your customer to the portal
|
|
1625
|
+
res.redirect(session.customerPortalUrl);
|
|
1626
|
+
```
|
|
1627
|
+
|
|
1628
|
+
Customers can use the portal to:
|
|
1629
|
+
|
|
1630
|
+
- View invoices
|
|
1631
|
+
- Update payment method
|
|
1632
|
+
- Cancel subscription
|
|
1633
|
+
- Manage billing details
|
|
1634
|
+
- Access downloads
|
|
1635
|
+
- View license keys
|
|
1636
|
+
|
|
1637
|
+
## Signed customer portal link from order details
|
|
1638
|
+
|
|
1639
|
+
You can now generate and send a signed customer portal link directly from the order details page. This is especially useful for support workflows.
|
|
1640
|
+
|
|
1641
|
+
**Example:** A customer asks:
|
|
1642
|
+
|
|
1643
|
+
```text
|
|
1644
|
+
Can you send me my invoice?
|
|
1645
|
+
I need to update my payment method.
|
|
1646
|
+
I need access to my license details.
|
|
1647
|
+
```
|
|
1648
|
+
You can open the order, generate a secure customer portal link, and send it to the customer. Customers can then access invoices, update their payment method, manage subscriptions, and view license details on their own. No custom engineering is required for this support workflow.
|
|
1649
|
+
|
|
1650
|
+
## Webhooks in the dashboard
|
|
1651
|
+
|
|
1652
|
+
We added webhook support in the dashboard. This gives developers a clear place to manage webhook related setup. Webhooks are useful when your app needs to react to Kelviq events.
|
|
1653
|
+
|
|
1654
|
+
Examples:
|
|
1655
|
+
|
|
1656
|
+
- Create a license after checkout
|
|
1657
|
+
- Unlock a paid feature
|
|
1658
|
+
- Update a subscription
|
|
1659
|
+
- Sync customer state
|
|
1660
|
+
- Send an onboarding email
|
|
1661
|
+
- Disable access after cancellation
|
|
1662
|
+
|
|
1663
|
+
## Webhook improvements in the Node SDK
|
|
1664
|
+
|
|
1665
|
+
The Node SDK now includes webhook improvements. This helps developers verify and handle webhook events more safely.
|
|
1666
|
+
|
|
1667
|
+
Example events:
|
|
1668
|
+
|
|
1669
|
+
```text
|
|
1670
|
+
checkout.completed
|
|
1671
|
+
order.created
|
|
1672
|
+
subscription.created
|
|
1673
|
+
subscription.updated
|
|
1674
|
+
subscription.cancelled
|
|
1675
|
+
plan.changed
|
|
1676
|
+
```
|
|
1677
|
+
|
|
1678
|
+
## Webhook logs
|
|
1679
|
+
|
|
1680
|
+
Kelviq now includes webhook logs. This helps developers debug webhook delivery issues. This is useful when your endpoint is down, slow, or returning an error. You can inspect:
|
|
1681
|
+
|
|
1682
|
+
- Event type
|
|
1683
|
+
- Delivery status
|
|
1684
|
+
- Response code
|
|
1685
|
+
- Timestamp
|
|
1686
|
+
- Error response
|
|
1687
|
+
|
|
1688
|
+
## Plan changed webhook
|
|
1689
|
+
|
|
1690
|
+
We added a plan changed webhook. This helps your app react when a customer changes plans.
|
|
1691
|
+
|
|
1692
|
+
Example: A customer moves from `Starter` to `Pro`.
|
|
1693
|
+
|
|
1694
|
+
Your app can listen for the event and update:
|
|
1695
|
+
|
|
1696
|
+
- Feature access
|
|
1697
|
+
- Usage limits
|
|
1698
|
+
- Seat limits
|
|
1699
|
+
- Credit balance
|
|
1700
|
+
- Internal customer state
|
|
1701
|
+
|
|
1702
|
+
## Publish plan UI and UX update
|
|
1703
|
+
|
|
1704
|
+
We updated the publish plan UI and UX. The new flow makes it clearer when a plan is still a draft and when it is ready for customers. This helps reduce mistakes before sharing checkout links.
|
|
1705
|
+
|
|
1706
|
+
## Plan description in plan detail header
|
|
1707
|
+
|
|
1708
|
+
Plan detail pages now show the plan description in the header. This makes it easier to identify similar plans.
|
|
1709
|
+
|
|
1710
|
+
Example:
|
|
1711
|
+
|
|
1712
|
+
```text
|
|
1713
|
+
Pro
|
|
1714
|
+
For growing AI teams with higher usage limits
|
|
1715
|
+
```
|
|
1716
|
+
|
|
1717
|
+
## Free plan switch disabled for published plans
|
|
1718
|
+
|
|
1719
|
+
Kelviq now disables free plan switching for published plans when switching is not possible. This prevents users from selecting an action that cannot be completed.
|
|
1720
|
+
|
|
1721
|
+
</Update>
|
|
1722
|
+
|
|
1723
|
+
<Update label="v1.8" description="June 5, 2026" tags={["App"]}>
|
|
1724
|
+
|
|
1725
|
+

|
|
1726
|
+
|
|
1727
|
+
## Usage based pricing in the dashboard
|
|
1728
|
+
|
|
1729
|
+
Merchants can configure metered pricing without leaving the dashboard. A plan can include a base subscription, included usage, and overage pricing for usage beyond the included amount.
|
|
1730
|
+
|
|
1731
|
+
## Pay as you go
|
|
1732
|
+
|
|
1733
|
+
Kelviq now supports pay as you go pricing. Your customers can continue using a metered product after included usage runs out, then pay for additional consumption. This fits LLM tools, API platforms, transcription products, and image generation products where hard cutoffs create poor customer experiences.
|
|
1734
|
+
|
|
1735
|
+
Example: A customer uses the following in one month:
|
|
1736
|
+
|
|
1737
|
+
```text
|
|
1738
|
+
120,000 tokens
|
|
1739
|
+
40 image generations
|
|
1740
|
+
500 API calls
|
|
1741
|
+
```
|
|
1742
|
+
|
|
1743
|
+
Kelviq will calculate the bill based on the pricing rules you set.
|
|
1744
|
+
|
|
1745
|
+
## Enable pay as you go from the dashboard
|
|
1746
|
+
|
|
1747
|
+
You can now enable pay as you go from the dashboard. This helps sellers launch usage based pricing without building their own billing system. A simple AI product can now charge like this:
|
|
1748
|
+
|
|
1749
|
+
```text
|
|
1750
|
+
Base plan: $20 per month
|
|
1751
|
+
Included usage: 100,000 tokens
|
|
1752
|
+
Overage: $2 per 10,000 tokens
|
|
1753
|
+
```
|
|
1754
|
+
|
|
1755
|
+
## Usage alerts
|
|
1756
|
+
|
|
1757
|
+
Kelviq now supports usage alerts. Usage alerts help you know when a customer reaches an important usage threshold. Merchants can notify customers when metered usage crosses a configured limit. This is especially useful for AI products where usage can grow quickly across tokens, image generations, API calls, embeddings, storage, or compute minutes.
|
|
1758
|
+
|
|
1759
|
+
Examples:
|
|
1760
|
+
|
|
1761
|
+
- Customer used 80% of included credits
|
|
1762
|
+
- Customer crossed 10,000 API calls
|
|
1763
|
+
- Customer used more than `$100` in AI model cost
|
|
1764
|
+
- Customer is close to the monthly usage limit
|
|
1765
|
+
- Customer is likely to need an upgrade soon
|
|
1766
|
+
|
|
1767
|
+
This helps sellers avoid surprise bills and give customers a better experience.
|
|
1768
|
+
|
|
1769
|
+
## Usage alerts for status entitlements
|
|
1770
|
+
|
|
1771
|
+
Usage alerts now work with status entitlements. This helps connect product access with usage state.
|
|
1772
|
+
|
|
1773
|
+
Example: A customer has `100` credits. Different features can consume credits differently:
|
|
1774
|
+
|
|
1775
|
+
```text
|
|
1776
|
+
GPT 5.1 request: 2 credits
|
|
1777
|
+
Claude Sonnet request: 3 credits
|
|
1778
|
+
Page crawl: 5 credits
|
|
1779
|
+
Long report generation: 20 credits
|
|
1780
|
+
```
|
|
1781
|
+
|
|
1782
|
+
Kelviq can help track when the customer is close to the limit and trigger an alert.
|
|
1783
|
+
|
|
1784
|
+
## Negative usage values
|
|
1785
|
+
|
|
1786
|
+
Usage reporting now supports negative values. This is useful when you need to correct usage after it was reported. If an app accidentally reports `125,000` tokens instead of `120,000`, it can send `-5,000` to bring the meter back in line.
|
|
1787
|
+
|
|
1788
|
+
Examples:
|
|
1789
|
+
|
|
1790
|
+
- Remove duplicate API usage
|
|
1791
|
+
- Reverse usage after a failed job
|
|
1792
|
+
- Credit back usage after a refund
|
|
1793
|
+
- Fix a metering mistake
|
|
1794
|
+
- Adjust token usage after an LLM call failed
|
|
1795
|
+
- Reserve tokens up front and return the unused amount once the action completes
|
|
1796
|
+
|
|
1797
|
+
This also enables a reserve-and-settle pattern. You can block a number of tokens in advance, then report a negative value to return whatever wasn't used once the action finishes. For example, reserve `1,000` tokens before an LLM call, then send `-400` if only `600` were consumed.
|
|
1798
|
+
|
|
1799
|
+
```js
|
|
1800
|
+
import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';
|
|
1801
|
+
|
|
1802
|
+
// Reserve tokens before the action
|
|
1803
|
+
await client.reporting.reportUsage({
|
|
1804
|
+
value: 1000,
|
|
1805
|
+
customerId: "cus_123",
|
|
1806
|
+
featureId: "tokens",
|
|
1807
|
+
behaviour: BEHAVIOUR_CHOICES.DELTA
|
|
1808
|
+
});
|
|
1809
|
+
|
|
1810
|
+
// Return the unused tokens after it completes
|
|
1811
|
+
await client.reporting.reportUsage({
|
|
1812
|
+
value: -400,
|
|
1813
|
+
customerId: "cus_123",
|
|
1814
|
+
featureId: "tokens",
|
|
1815
|
+
behaviour: BEHAVIOUR_CHOICES.DELTA
|
|
1816
|
+
});
|
|
1817
|
+
```
|
|
1818
|
+
|
|
1819
|
+
## Checkout API supports locked email and default billing country
|
|
1820
|
+
|
|
1821
|
+
The checkout API now supports locked email and default billing country. This helps create a cleaner checkout flow when your app already knows the customer.
|
|
1822
|
+
|
|
1823
|
+
Example:
|
|
1824
|
+
|
|
1825
|
+
```js
|
|
1826
|
+
await client.checkout.createSession({
|
|
1827
|
+
planIdentifier: "plan-pro",
|
|
1828
|
+
customerId: "cust_789",
|
|
1829
|
+
lockEmail: true,
|
|
1830
|
+
defaultBillingCountry: "US"
|
|
1831
|
+
});
|
|
1832
|
+
```
|
|
1833
|
+
|
|
1834
|
+
This prevents customers from using the wrong email during checkout.
|
|
1835
|
+
|
|
1836
|
+
## Prefill customer email in checkout links
|
|
1837
|
+
|
|
1838
|
+
Checkout links can now prefill the customer email when available. This is useful when checkout starts from your app.
|
|
1839
|
+
|
|
1840
|
+
Example: A logged in customer clicks upgrade. Checkout opens with their email already filled in.
|
|
1841
|
+
|
|
1842
|
+
```text
|
|
1843
|
+
alex@company.com
|
|
1844
|
+
```
|
|
1845
|
+
|
|
1846
|
+
This reduces checkout mistakes and support issues.
|
|
1847
|
+
|
|
1848
|
+
## Lock email using checkout config
|
|
1849
|
+
|
|
1850
|
+
Checkout links now support locking the email field using config. This means customers can see the email but cannot edit it.
|
|
1851
|
+
|
|
1852
|
+
This is useful for:
|
|
1853
|
+
|
|
1854
|
+
- License keys
|
|
1855
|
+
- Account based access
|
|
1856
|
+
- Customer portal access
|
|
1857
|
+
- Subscription upgrades
|
|
1858
|
+
- Team plans
|
|
1859
|
+
|
|
1860
|
+
## SEPA payment method
|
|
1861
|
+
|
|
1862
|
+
Checkout now supports SEPA. This helps sellers serve more European customers, especially B2B customers who prefer bank debit. SEPA is useful for:
|
|
1863
|
+
|
|
1864
|
+
- SaaS subscriptions
|
|
1865
|
+
- B2B tools
|
|
1866
|
+
- Annual contracts
|
|
1867
|
+
- European customers
|
|
1868
|
+
- Larger invoice amounts
|
|
1869
|
+
|
|
1870
|
+
</Update>
|
|
1871
|
+
|
|
1872
|
+
<Update label="v2.6.0" description="June 5, 2026" tags={["Node SDK"]}>
|
|
1873
|
+
|
|
1874
|
+
### New Features
|
|
1875
|
+
|
|
1876
|
+
#### Checkout Session — `metadata` Parameter
|
|
1877
|
+
|
|
1878
|
+
`CreateCheckoutSessionPayload` now accepts an optional `metadata` field for attaching arbitrary key-value pairs to a checkout session. The metadata is returned verbatim on the `checkout.completed` webhook payload's `metadata` field, letting you correlate a completed checkout back to your own records.
|
|
1879
|
+
|
|
1880
|
+
```typescript
|
|
1881
|
+
const response = await client.checkout.createSession({
|
|
1882
|
+
planIdentifier: "plan-pro-monthly",
|
|
1883
|
+
chargePeriod: "MONTHLY",
|
|
1884
|
+
customerId: "cust_789",
|
|
1885
|
+
successUrl: "https://example.com/success",
|
|
1886
|
+
metadata: {
|
|
1887
|
+
orderId: "order_12345",
|
|
1888
|
+
referralCode: "SUMMER2026",
|
|
1889
|
+
},
|
|
1890
|
+
});
|
|
1891
|
+
```
|
|
1892
|
+
|
|
1893
|
+
Unlike other payload fields, the **keys inside `metadata` are preserved exactly as provided** — they are not converted to snake_case on the way to the API, so they survive the round-trip back through webhooks unchanged.
|
|
1894
|
+
|
|
1895
|
+
</Update>
|
|
1896
|
+
|
|
1897
|
+
<Update label="v2.6.0" description="June 5, 2026" tags={["Python SDK"]}>
|
|
1898
|
+
|
|
1899
|
+
### New Features
|
|
1900
|
+
|
|
1901
|
+
#### Checkout Session — `metadata` Parameter
|
|
1902
|
+
|
|
1903
|
+
`checkout.create_session()` now accepts an optional `metadata` parameter for attaching arbitrary key-value pairs to a checkout session. The metadata is returned verbatim on the `checkout.completed` webhook payload's `metadata` field, letting you correlate a completed checkout back to your own records.
|
|
1904
|
+
|
|
1905
|
+
```python
|
|
1906
|
+
response = client.checkout.create_session(
|
|
1907
|
+
planIdentifier="plan-pro-monthly",
|
|
1908
|
+
chargePeriod="MONTHLY",
|
|
1909
|
+
customerId="cust_789",
|
|
1910
|
+
successUrl="https://example.com/success",
|
|
1911
|
+
metadata={
|
|
1912
|
+
"orderId": "order_12345",
|
|
1913
|
+
"referralCode": "SUMMER2026",
|
|
1914
|
+
},
|
|
1915
|
+
)
|
|
1916
|
+
```
|
|
1917
|
+
|
|
1918
|
+
**Async variant:**
|
|
1919
|
+
|
|
1920
|
+
```python
|
|
1921
|
+
response = await async_client.checkout.create_session(
|
|
1922
|
+
planIdentifier="plan-pro-monthly",
|
|
1923
|
+
chargePeriod="MONTHLY",
|
|
1924
|
+
customerId="cust_789",
|
|
1925
|
+
successUrl="https://example.com/success",
|
|
1926
|
+
metadata={"orderId": "order_12345"},
|
|
1927
|
+
)
|
|
1928
|
+
```
|
|
1929
|
+
|
|
1930
|
+
The keys inside `metadata` are preserved exactly as provided — they are not transformed on the way to the API, so they survive the round-trip back through webhooks unchanged.
|
|
1931
|
+
|
|
1932
|
+
</Update>
|
|
1933
|
+
|
|
1934
|
+
<Update label="v1.7" description="May 29, 2026" tags={["App"]}>
|
|
1935
|
+
|
|
1936
|
+

|
|
1937
|
+
|
|
1938
|
+
## Tax inclusive pricing settings
|
|
1939
|
+
|
|
1940
|
+
Kelviq now supports tax inclusive pricing settings. This lets you decide whether the price shown to the customer already includes tax.
|
|
1941
|
+
|
|
1942
|
+
Example: A customer sees:
|
|
1943
|
+
|
|
1944
|
+
```text
|
|
1945
|
+
$20 per month
|
|
1946
|
+
```
|
|
1947
|
+
|
|
1948
|
+
If tax inclusive pricing is enabled, the customer still pays $20 per month.
|
|
1949
|
+
|
|
1950
|
+
Kelviq calculates the tax portion from that amount. This is useful in markets where customers expect the displayed price to be the final price.
|
|
1951
|
+
|
|
1952
|
+
## Tax inclusive behavior is shown in checkout
|
|
1953
|
+
|
|
1954
|
+
Checkout now respects tax inclusive settings so the buyer sees the same pricing behavior that was configured for the plan. This avoids the common confusion where a pricing page says `$49` but checkout unexpectedly adds tax on top.
|
|
1955
|
+
|
|
1956
|
+
## Tax type and tax percentage in checkout
|
|
1957
|
+
|
|
1958
|
+
Checkout links now support tax type (such as VAT, GST, Sales Tax, or any other configured tax type) and the tax percentage. This gives customers a clearer view of what they are paying.
|
|
1959
|
+
|
|
1960
|
+
Example with tax added on top:
|
|
1961
|
+
|
|
1962
|
+
```text
|
|
1963
|
+
Product price: $100
|
|
1964
|
+
Tax: 10%
|
|
1965
|
+
Total: $110
|
|
1966
|
+
```
|
|
1967
|
+
|
|
1968
|
+
Example with tax included:
|
|
1969
|
+
|
|
1970
|
+
```text
|
|
1971
|
+
Total: €20
|
|
1972
|
+
Includes tax: €3.33
|
|
1973
|
+
```
|
|
1974
|
+
|
|
1975
|
+
## Tax behavior in plan details
|
|
1976
|
+
|
|
1977
|
+
Plan detail pages now show tax behavior. Teams can confirm that a `Pro EU` plan includes VAT, while a `Pro US` plan remains tax exclusive. You can see whether a plan is tax inclusive or tax exclusive before sharing it with customers, helping you avoid setup mistakes.
|
|
1978
|
+
|
|
1979
|
+
## Tax code category on products
|
|
1980
|
+
|
|
1981
|
+
You can now set a tax code category when creating or editing a product. This helps Kelviq apply the right tax treatment based on what you sell.
|
|
1982
|
+
|
|
1983
|
+
Examples:
|
|
1984
|
+
|
|
1985
|
+
- SaaS subscription
|
|
1986
|
+
- API access
|
|
1987
|
+
- AI credits
|
|
1988
|
+
- Digital download
|
|
1989
|
+
- License key
|
|
1990
|
+
- Course
|
|
1991
|
+
- Template
|
|
1992
|
+
- Plugin
|
|
1993
|
+
|
|
1994
|
+
This matters because different product types can have different tax rules.
|
|
1995
|
+
|
|
1996
|
+
## Tax information in transactions
|
|
1997
|
+
|
|
1998
|
+
Transaction views now show tax details so support and finance teams can answer customer questions without leaving the dashboard.
|
|
1999
|
+
|
|
2000
|
+
You can use this to answer questions like:
|
|
2001
|
+
|
|
2002
|
+
- What was the product price?
|
|
2003
|
+
- How much tax was charged?
|
|
2004
|
+
- Was tax included in the price?
|
|
2005
|
+
- What did the customer pay in total?
|
|
2006
|
+
|
|
2007
|
+
## Custom checkout pricing
|
|
2008
|
+
|
|
2009
|
+
Kelviq now supports custom checkout pricing. This lets you create a checkout with a custom amount instead of always using the fixed public plan price.
|
|
2010
|
+
|
|
2011
|
+
This is useful for:
|
|
2012
|
+
|
|
2013
|
+
- Custom quotes
|
|
2014
|
+
- One off payments
|
|
2015
|
+
- Sales led plans
|
|
2016
|
+
- Manual upgrades
|
|
2017
|
+
- Private deals
|
|
2018
|
+
- Customer specific pricing
|
|
2019
|
+
|
|
2020
|
+
Example: A customer agrees to a custom price of `$349 per month`.
|
|
2021
|
+
|
|
2022
|
+
You can create a checkout session for that amount without creating a public plan for every custom price.
|
|
2023
|
+
|
|
2024
|
+
## Custom amount on checkout page
|
|
2025
|
+
|
|
2026
|
+
Checkout can now show and charge a custom amount. This gives sellers more flexibility when dealing with larger customers or special pricing cases.
|
|
2027
|
+
|
|
2028
|
+
Example:
|
|
2029
|
+
|
|
2030
|
+
```text
|
|
2031
|
+
Custom plan
|
|
2032
|
+
$349 per month
|
|
2033
|
+
```
|
|
2034
|
+
|
|
2035
|
+
## Regional pricing minimum value validation
|
|
2036
|
+
|
|
2037
|
+
We added validation for regional pricing minimum values. This helps prevent a regional price from becoming too low to process.
|
|
2038
|
+
|
|
2039
|
+
Example: A plan is priced at `$5`.
|
|
2040
|
+
|
|
2041
|
+
A very large regional discount could reduce the price below the minimum amount allowed by the payment method. Kelviq now catches this earlier so sellers can fix it before customers reach checkout.
|
|
2042
|
+
|
|
2043
|
+
## Fixes
|
|
2044
|
+
|
|
2045
|
+
**Canada postal code** —
|
|
2046
|
+
Fixed an issue with Canadian postal codes during checkout. Canadian postal codes such as `M5V 2T6` are now handled correctly.
|
|
2047
|
+
|
|
2048
|
+
**Checkout plan switching** —
|
|
2049
|
+
Fixed an issue where checkout could fail when customers switched between plans. This improves checkout reliability when customers compare plans before paying.
|
|
2050
|
+
|
|
2051
|
+
**Package pricing label** —
|
|
2052
|
+
Fixed the label for package based pricing. This makes package pricing easier for customers to understand at checkout.
|
|
2053
|
+
|
|
2054
|
+
Example:
|
|
2055
|
+
```text
|
|
2056
|
+
$10 per 1,000 API calls
|
|
2057
|
+
```
|
|
2058
|
+
|
|
2059
|
+
**One time payment cancellation** —
|
|
2060
|
+
Fixed an issue where cancel subscription was visible for one time payments. One time payments do not have a subscription to cancel, so that action is now hidden.
|
|
2061
|
+
|
|
2062
|
+
</Update>
|
|
2063
|
+
|
|
2064
|
+
<Update label="v1.6" description="May 22, 2026" tags={["App"]}>
|
|
2065
|
+
|
|
2066
|
+

|
|
2067
|
+
|
|
2068
|
+
## Promotions are now faster and more reliable
|
|
2069
|
+
|
|
2070
|
+
We moved Promotions storage to DynamoDB. This gives promotion rules
|
|
2071
|
+
a durable home across the dashboard, APIs, and hosted checkout.
|
|
2072
|
+
|
|
2073
|
+
Example: A merchant selling an AI support agent can create `STARTUP20`,
|
|
2074
|
+
limit it to the Pro plan, and keep the rule available when checkout
|
|
2075
|
+
links are regenerated.
|
|
2076
|
+
|
|
2077
|
+
## Promotions are now available in the dashboard
|
|
2078
|
+
|
|
2079
|
+
We added Promotions to the Kelviq dashboard. Teams can now create,
|
|
2080
|
+
review, and manage offers without asking engineering to touch config.
|
|
2081
|
+
The flow is built around what a billing owner actually needs to know:
|
|
2082
|
+
which plan is discounted, whether the promotion is active, and where
|
|
2083
|
+
the SDK docs are when you need to wire it up from code.
|
|
2084
|
+
|
|
2085
|
+
A common flow looks like this:
|
|
2086
|
+
|
|
2087
|
+
1. Create a product
|
|
2088
|
+
2. Create a plan
|
|
2089
|
+
3. Add a promotion
|
|
2090
|
+
4. Copy the checkout link
|
|
2091
|
+
5. Share the link or add it to your pricing page
|
|
2092
|
+
|
|
2093
|
+
## API and SDK docs are linked from Promotions
|
|
2094
|
+
|
|
2095
|
+
The dashboard now connects promotion setup to the integration docs a developer needs when creating checkout sessions from the backend. This helps developers move from setup to integration faster.
|
|
2096
|
+
|
|
2097
|
+
## Checkout link empty screen is clearer
|
|
2098
|
+
|
|
2099
|
+
The empty screen now points users toward creating or copying the right checkout link instead of leaving the page feeling broken.
|
|
2100
|
+
|
|
2101
|
+
## Checkout links are easier to access
|
|
2102
|
+
|
|
2103
|
+
You can now get checkout links from product and plan listing pages. This saves time when you are setting up a product and want to quickly copy a checkout link.
|
|
2104
|
+
|
|
2105
|
+
## Product cards are now fully clickable
|
|
2106
|
+
|
|
2107
|
+
Instead of clicking only on a small button or title, you can click anywhere on the product card to open it. This makes navigation easier when you have multiple products.
|
|
2108
|
+
|
|
2109
|
+
## Developers tab is now API Key
|
|
2110
|
+
|
|
2111
|
+
We renamed the Developers tab to API Key. Most people go there to find their API key, so the label now matches the destination.
|
|
2112
|
+
|
|
2113
|
+
Before: **Developers**
|
|
2114
|
+
|
|
2115
|
+
Now: **API Key**
|
|
2116
|
+
|
|
2117
|
+
## Chart theming support
|
|
2118
|
+
|
|
2119
|
+
We added theming options for charts, including branded and dark mode. Charts now stay consistent with the rest of your dashboard without manual workarounds.
|
|
2120
|
+
|
|
2121
|
+
## Analytics style update
|
|
2122
|
+
|
|
2123
|
+
We updated the analytics UI style to make revenue, customers,
|
|
2124
|
+
transactions, and product data easier to scan.
|
|
2125
|
+
|
|
2126
|
+
This is helpful when you want to quickly answer questions like:
|
|
2127
|
+
|
|
2128
|
+
- How much did we sell today?
|
|
2129
|
+
- Which plan is performing better?
|
|
2130
|
+
- Which product has the most transactions?
|
|
2131
|
+
- Are refunds increasing?
|
|
2132
|
+
- Are more customers choosing annual plans?
|
|
2133
|
+
|
|
2134
|
+
## Docs copy cleanup
|
|
2135
|
+
|
|
2136
|
+
We updated docs copy from `archive` to `delete` in more places.
|
|
2137
|
+
This makes the docs match the real product action.
|
|
2138
|
+
|
|
2139
|
+
## Fixes
|
|
2140
|
+
|
|
2141
|
+
**Duplicate file upload issue** —
|
|
2142
|
+
Fixed an issue where duplicate files could be created during
|
|
2143
|
+
multiple file uploads.
|
|
2144
|
+
|
|
2145
|
+
**Plan dialog issue** —
|
|
2146
|
+
Fixed an issue where the add plan dialog closed even when the
|
|
2147
|
+
user selected the option to create more plans. Now users can
|
|
2148
|
+
create multiple plans without reopening the dialog each time.
|
|
2149
|
+
|
|
2150
|
+
**Feature delete issue** —
|
|
2151
|
+
Fixed an issue where a feature was not removed correctly from
|
|
2152
|
+
the list after deletion.
|
|
2153
|
+
|
|
2154
|
+
</Update>
|
|
2155
|
+
|
|
2156
|
+
<Update label="v1.5" description="May 15, 2026" tags={["App"]}>
|
|
2157
|
+
|
|
2158
|
+
### Payments & Billing
|
|
2159
|
+
- **UPI Payments Support** — You can now accept payments via UPI. Customers can pay seamlessly using their preferred UPI apps (like Google Pay, PhonePe, or Paytm).
|
|
2160
|
+
- **Usage-Based Billing** — You can now bill customers based on their actual consumption. This provides maximum flexibility for products using credits, seats, or data metrics.
|
|
2161
|
+
|
|
2162
|
+
### Customer Experience
|
|
2163
|
+
- **Signed Customer Portal Links** — Added the option to generate and send a signed customer portal link directly from the order details page for secure, instant access.
|
|
2164
|
+
|
|
2165
|
+
### Tax & Compliance
|
|
2166
|
+
- **Tax Information** — Tax detail is added in transaction.
|
|
2167
|
+
- **Tax Categories** — You can now define **Tax Categories** (B2B, B2C, Ebook, Online Course, etc.) during product creation.
|
|
2168
|
+
- **Business Tax ID Support** — Control how valid business tax IDs are handled for tax-inclusive pricing. When enabled, Kelviq automatically removes the included tax amount from the checkout total if a customer provides a valid business tax ID during checkout. When disabled, customers continue paying the listed tax-inclusive price with no tax deduction applied.
|
|
2169
|
+
|
|
2170
|
+
</Update>
|
|
2171
|
+
|
|
2172
|
+
<Update label="v2.5.0" description="May 10, 2026" tags={["Node SDK"]}>
|
|
2173
|
+
|
|
2174
|
+
### New Features
|
|
2175
|
+
|
|
2176
|
+
#### Subscription Update — `trialEnd` Parameter
|
|
2177
|
+
|
|
2178
|
+
`subscriptions.update()` now accepts an optional `trialEnd` field on `UpdateSubscriptionPayload` to control the trial period when updating a subscription.
|
|
2179
|
+
|
|
2180
|
+
Pass either:
|
|
2181
|
+
|
|
2182
|
+
- The literal string `"now"` to end any active trial immediately.
|
|
2183
|
+
- An ISO 8601 datetime string (e.g. `"2025-12-31T23:59:59Z"`) to set a new trial end date. The datetime must be in the future. Naive datetimes (no timezone designator) are interpreted as UTC.
|
|
2184
|
+
- Omit the field to preserve the existing trial behavior on the subscription.
|
|
2185
|
+
|
|
2186
|
+
```typescript
|
|
2187
|
+
import { CHARGE_PERIOD_CHOICES } from '@kelviq/node-sdk';
|
|
2188
|
+
|
|
2189
|
+
// End the trial now
|
|
2190
|
+
await client.subscriptions.update({
|
|
2191
|
+
subscriptionId: "sub_node_78058918",
|
|
2192
|
+
planIdentifier: "premium-plan-node",
|
|
2193
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
2194
|
+
trialEnd: "now",
|
|
2195
|
+
});
|
|
2196
|
+
|
|
2197
|
+
// Extend the trial to a specific future date
|
|
2198
|
+
await client.subscriptions.update({
|
|
2199
|
+
subscriptionId: "sub_node_78058918",
|
|
2200
|
+
planIdentifier: "premium-plan-node",
|
|
2201
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
2202
|
+
trialEnd: "2025-12-31T23:59:59Z",
|
|
2203
|
+
});
|
|
2204
|
+
```
|
|
2205
|
+
|
|
2206
|
+
The SDK validates `trialEnd` client-side — invalid datetime strings or past datetimes throw `InvalidRequestError` before the request is sent.
|
|
2207
|
+
|
|
2208
|
+
</Update>
|
|
2209
|
+
|
|
2210
|
+
<Update label="v2.5.0" description="May 10, 2026" tags={["Python SDK"]}>
|
|
2211
|
+
|
|
2212
|
+
### New Features
|
|
2213
|
+
|
|
2214
|
+
#### Subscription Update — `trialEnd` Parameter
|
|
2215
|
+
|
|
2216
|
+
`subscriptions.update()` now accepts an optional `trialEnd` parameter to control the trial period when updating a subscription.
|
|
2217
|
+
|
|
2218
|
+
Pass either:
|
|
2219
|
+
|
|
2220
|
+
- The literal string `"now"` to end any active trial immediately.
|
|
2221
|
+
- An ISO 8601 datetime string (e.g. `"2025-12-31 23:59:59"`) to set a new trial end date. The datetime must be in the future. Naive datetimes are interpreted as UTC.
|
|
2222
|
+
- Omit the parameter to preserve the existing trial behavior on the subscription.
|
|
2223
|
+
|
|
2224
|
+
```python
|
|
2225
|
+
# End the trial now
|
|
2226
|
+
response = client.subscriptions.update(
|
|
2227
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
2228
|
+
planIdentifier="premium-plan",
|
|
2229
|
+
chargePeriod="MONTHLY",
|
|
2230
|
+
trialEnd="now",
|
|
2231
|
+
)
|
|
2232
|
+
|
|
2233
|
+
# Extend the trial to a specific future date
|
|
2234
|
+
response = client.subscriptions.update(
|
|
2235
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
2236
|
+
planIdentifier="premium-plan",
|
|
2237
|
+
chargePeriod="MONTHLY",
|
|
2238
|
+
trialEnd="2025-12-31 23:59:59",
|
|
2239
|
+
)
|
|
2240
|
+
```
|
|
2241
|
+
|
|
2242
|
+
**Async variant:**
|
|
2243
|
+
|
|
2244
|
+
```python
|
|
2245
|
+
response = await async_client.subscriptions.update(
|
|
2246
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
2247
|
+
planIdentifier="premium-plan",
|
|
2248
|
+
chargePeriod="MONTHLY",
|
|
2249
|
+
trialEnd="2025-12-31 23:59:59",
|
|
2250
|
+
)
|
|
2251
|
+
```
|
|
2252
|
+
|
|
2253
|
+
The SDK validates `trialEnd` client-side — invalid datetime strings or past datetimes raise `InvalidRequestError` before the request is sent.
|
|
2254
|
+
|
|
2255
|
+
</Update>
|
|
2256
|
+
|
|
2257
|
+
<Update label="v2.1.0" description="May 9, 2026" tags={["JS SDK"]}>
|
|
2258
|
+
### New Features
|
|
2259
|
+
|
|
2260
|
+
#### Product Offerings — Pricing API Support
|
|
2261
|
+
|
|
2262
|
+
The SDK can now fetch and display product pricing data. Pass a `productId` to the client to enable pricing methods.
|
|
2263
|
+
|
|
2264
|
+
```ts
|
|
2265
|
+
const client = kelviqSDK({
|
|
2266
|
+
productId: 'your-product-id',
|
|
2267
|
+
accessToken: 'your-access-token',
|
|
2268
|
+
});
|
|
2269
|
+
```
|
|
2270
|
+
|
|
2271
|
+
If `customerId` is also set, it is forwarded to the pricing API so the response reflects that customer's subscription state.
|
|
2272
|
+
|
|
2273
|
+
---
|
|
2274
|
+
|
|
2275
|
+
##### `fetchPricing(forceRefresh?)` — Fetch and Cache Pricing
|
|
2276
|
+
|
|
2277
|
+
Fetches product offering data for the configured `productId`. Subsequent calls return the cached result unless `forceRefresh` is `true`.
|
|
2278
|
+
|
|
2279
|
+
```ts
|
|
2280
|
+
const pricing = await client.fetchPricing();
|
|
2281
|
+
console.log(pricing.plans, pricing.currencyCode, pricing.billingPeriods);
|
|
2282
|
+
|
|
2283
|
+
await client.fetchPricing(true); // bypass cache
|
|
2284
|
+
```
|
|
2285
|
+
|
|
2286
|
+
##### `getPricing()` — Read from Cache
|
|
2287
|
+
|
|
2288
|
+
Returns cached pricing data synchronously, or `null` if not yet fetched.
|
|
2289
|
+
|
|
2290
|
+
```ts
|
|
2291
|
+
const pricing = client.getPricing();
|
|
2292
|
+
```
|
|
2293
|
+
|
|
2294
|
+
##### `getPlan(identifier)` — Look Up a Single Plan
|
|
2295
|
+
|
|
2296
|
+
Finds an enabled plan by identifier from the pricing cache. Returns `null` if not found or pricing hasn't been fetched.
|
|
2297
|
+
|
|
2298
|
+
```ts
|
|
2299
|
+
const plan = client.getPlan('pro-plan');
|
|
2300
|
+
console.log(plan?.displayName, plan?.price.priceType);
|
|
2301
|
+
```
|
|
2302
|
+
|
|
2303
|
+
##### `isPricingLoading()` — Loading State
|
|
2304
|
+
|
|
2305
|
+
Returns `true` while a pricing fetch is in progress.
|
|
2306
|
+
|
|
2307
|
+
```ts
|
|
2308
|
+
if (client.isPricingLoading()) { /* show spinner */ }
|
|
2309
|
+
```
|
|
2310
|
+
|
|
2311
|
+
##### `getLastPricingError()` — Error State
|
|
2312
|
+
|
|
2313
|
+
Returns the last `Error` from a failed pricing fetch, or `null`.
|
|
2314
|
+
|
|
2315
|
+
```ts
|
|
2316
|
+
const err = client.getLastPricingError();
|
|
2317
|
+
```
|
|
2318
|
+
|
|
2319
|
+
##### `clearPricingCache()` — Reset Cache
|
|
2320
|
+
|
|
2321
|
+
Clears cached pricing data and resets loading and error states.
|
|
2322
|
+
|
|
2323
|
+
```ts
|
|
2324
|
+
client.clearPricingCache();
|
|
2325
|
+
```
|
|
2326
|
+
|
|
2327
|
+
---
|
|
2328
|
+
|
|
2329
|
+
##### `renderPricing(options?)` — DOM Binding
|
|
2330
|
+
|
|
2331
|
+
Scans the DOM for elements with `data-kq-price` attributes and populates them with localized formatted prices. Requires pricing data to be fetched first.
|
|
2332
|
+
|
|
2333
|
+
```html
|
|
2334
|
+
<span data-kq-price="pro-plan" data-kq-period="MONTHLY">Loading...</span>
|
|
2335
|
+
```
|
|
2336
|
+
|
|
2337
|
+
```ts
|
|
2338
|
+
await client.fetchPricing();
|
|
2339
|
+
client.renderPricing();
|
|
2340
|
+
|
|
2341
|
+
// Scope to a container
|
|
2342
|
+
client.renderPricing({ container: document.getElementById('pricing-section') });
|
|
2343
|
+
|
|
2344
|
+
// With format options
|
|
2345
|
+
client.renderPricing({ formatOptions: { compact: true } });
|
|
2346
|
+
```
|
|
2347
|
+
|
|
2348
|
+
| Attribute | Required | Description |
|
|
2349
|
+
|---|---|---|
|
|
2350
|
+
| `data-kq-price` | Yes | Plan identifier |
|
|
2351
|
+
| `data-kq-period` | No | Billing period (e.g. `MONTHLY`, `YEARLY`). Falls back to the first available charge. |
|
|
2352
|
+
|
|
2353
|
+
---
|
|
2354
|
+
|
|
2355
|
+
##### `kqFormatPrice(amount, currencySymbol, options?)` — Price Formatter
|
|
2356
|
+
|
|
2357
|
+
Standalone named export for formatting a numeric amount with a currency symbol.
|
|
2358
|
+
|
|
2359
|
+
```ts
|
|
2360
|
+
import { kqFormatPrice } from '@kelviq/js-sdk';
|
|
2361
|
+
|
|
2362
|
+
kqFormatPrice(9.99, '$', { pricingLocale: 'en-US' }); // "$9.99"
|
|
2363
|
+
kqFormatPrice(1200, '€', { compact: true, pricingLocale: 'de-DE' }); // "€1,2K"
|
|
2364
|
+
kqFormatPrice(9.99, '$', { includeCurrencySymbol: false }); // "9.99"
|
|
2365
|
+
```
|
|
2366
|
+
|
|
2367
|
+
| Option | Type | Default | Description |
|
|
2368
|
+
|---|---|---|---|
|
|
2369
|
+
| `compact` | `boolean` | `false` | Use compact notation (e.g. `1.2K`) |
|
|
2370
|
+
| `locale` | `string` | `pricingLocale` | Override locale for number formatting |
|
|
2371
|
+
| `pricingLocale` | `string` | `'en-US'` | Locale from the pricing API |
|
|
2372
|
+
| `includeCurrencySymbol` | `boolean` | `true` | Prepend the currency symbol |
|
|
2373
|
+
|
|
2374
|
+
---
|
|
2375
|
+
|
|
2376
|
+
##### New Types and Exports
|
|
2377
|
+
|
|
2378
|
+
```ts
|
|
2379
|
+
export { kqFormatPrice } from './formatPrice';
|
|
2380
|
+
export type { KQFormatPriceOptions } from './formatPrice';
|
|
2381
|
+
export type {
|
|
2382
|
+
RawPricingFeature,
|
|
2383
|
+
RawPricingCharge,
|
|
2384
|
+
RawPricingPrice,
|
|
2385
|
+
RawPricingPlan,
|
|
2386
|
+
RawPricingBillingPeriod,
|
|
2387
|
+
RawPricingApiResponse,
|
|
2388
|
+
} from './types';
|
|
2389
|
+
```
|
|
2390
|
+
|
|
2391
|
+
</Update>
|
|
2392
|
+
|
|
2393
|
+
<Update label="v2.1.1" description="May 9, 2026" tags={["React SDK"]}>
|
|
2394
|
+
### Improvements
|
|
2395
|
+
|
|
2396
|
+
#### `KelviqProvider` — `customerId` and `plansEnabled` Props for Pricing
|
|
2397
|
+
|
|
2398
|
+
The pricing request now forwards two additional optional props to the product offerings API.
|
|
2399
|
+
|
|
2400
|
+
**`customerId`** — when provided, the pricing response is personalized to that customer (e.g. reflecting their existing subscription state):
|
|
2401
|
+
|
|
2402
|
+
```tsx
|
|
2403
|
+
<KelviqProvider
|
|
2404
|
+
accessToken="..."
|
|
2405
|
+
productId="your-product-id"
|
|
2406
|
+
customerId="cust_123"
|
|
2407
|
+
config={{ fetchPricingOnMount: true }}
|
|
2408
|
+
>
|
|
2409
|
+
|
|
2410
|
+
</KelviqProvider>
|
|
2411
|
+
```
|
|
2412
|
+
|
|
2413
|
+
**`plansEnabled`** — a comma-separated list of plan identifiers to include in the response. When omitted, all active plans are returned:
|
|
2414
|
+
|
|
2415
|
+
```tsx
|
|
2416
|
+
<KelviqProvider
|
|
2417
|
+
accessToken="..."
|
|
2418
|
+
productId="your-product-id"
|
|
2419
|
+
plansEnabled="free-plan,pro-plan"
|
|
2420
|
+
config={{ fetchPricingOnMount: true }}
|
|
2421
|
+
>
|
|
2422
|
+
|
|
2423
|
+
</KelviqProvider>
|
|
2424
|
+
```
|
|
2425
|
+
|
|
2426
|
+
Both props are reactive — updating either value will trigger a new pricing fetch automatically.
|
|
2427
|
+
|
|
2428
|
+
</Update>
|
|
2429
|
+
|
|
2430
|
+
<Update label="v2.1.0" description="May 9, 2026" tags={["React SDK"]}>
|
|
2431
|
+
### New Features
|
|
2432
|
+
|
|
2433
|
+
#### Product Offerings — Pricing & Feature Components
|
|
2434
|
+
|
|
2435
|
+
The SDK now supports fetching and displaying product pricing and plan features, with localized currency based on user location.
|
|
2436
|
+
|
|
2437
|
+
##### Setup
|
|
2438
|
+
|
|
2439
|
+
Pass `productId` and enable `fetchPricingOnMount` in your provider config:
|
|
2440
|
+
|
|
2441
|
+
```tsx
|
|
2442
|
+
<KelviqProvider
|
|
2443
|
+
accessToken="..."
|
|
2444
|
+
productId="your-product-id"
|
|
2445
|
+
config={{ fetchPricingOnMount: true }}
|
|
2446
|
+
>
|
|
2447
|
+
|
|
2448
|
+
</KelviqProvider>
|
|
2449
|
+
```
|
|
2450
|
+
|
|
2451
|
+
##### `usePricing()` — Pricing Data Hook
|
|
2452
|
+
|
|
2453
|
+
Returns the full pricing API response as an `AsyncState`. Only populated when `fetchPricingOnMount` is enabled, or after calling `refreshPricing()` from `useKelviq()`.
|
|
2454
|
+
|
|
2455
|
+
```ts
|
|
2456
|
+
const { data, isLoading, error } = usePricing();
|
|
2457
|
+
console.log(data?.currencyCode, data?.plans);
|
|
2458
|
+
```
|
|
2459
|
+
|
|
2460
|
+
##### `` — Render-Prop Price Component
|
|
2461
|
+
|
|
2462
|
+
Displays localized pricing for a plan and billing period:
|
|
2463
|
+
|
|
2464
|
+
```tsx
|
|
2465
|
+
}
|
|
2466
|
+
fallback={<p>Unavailable</p>}
|
|
2467
|
+
>
|
|
2468
|
+
{({ formattedPrice, isFree, hasFreeTrial, trialPeriod }) => (
|
|
2469
|
+
<div>
|
|
2470
|
+
<span>{formattedPrice}</span>
|
|
2471
|
+
{hasFreeTrial && <span>Try free for {trialPeriod} days</span>}
|
|
2472
|
+
</div>
|
|
2473
|
+
)}
|
|
2474
|
+
</KQPrice>
|
|
2475
|
+
```
|
|
2476
|
+
|
|
2477
|
+
The render prop receives:
|
|
2478
|
+
|
|
2479
|
+
| Field | Type | Description |
|
|
2480
|
+
|---|---|---|
|
|
2481
|
+
| `plan` | `RawPricingPlan` | Full plan object |
|
|
2482
|
+
| `charge` | `RawPricingCharge \| null` | Charge for the requested billing period |
|
|
2483
|
+
| `amount` | `number` | Raw numeric amount |
|
|
2484
|
+
| `formattedPrice` | `string` | Localized price string (e.g. `$9.99`) or `"Free"` |
|
|
2485
|
+
| `currencySymbol` | `string` | e.g. `$` |
|
|
2486
|
+
| `currencyCode` | `string` | e.g. `USD` |
|
|
2487
|
+
| `pricingLocale` | `string` | e.g. `en-US` |
|
|
2488
|
+
| `isFree` | `boolean` | `true` when `priceType === 'FREE'` |
|
|
2489
|
+
| `hasFreeTrial` | `boolean` | Whether a free trial is available |
|
|
2490
|
+
| `trialPeriod` | `number` | Trial length in days |
|
|
2491
|
+
|
|
2492
|
+
##### `` — Render-Prop Feature Component
|
|
2493
|
+
|
|
2494
|
+
Iterates over enabled features for a plan. Supports optional filtering by feature type:
|
|
2495
|
+
|
|
2496
|
+
```tsx
|
|
2497
|
+
}
|
|
2498
|
+
fallback={<p>No features available</p>}
|
|
2499
|
+
>
|
|
2500
|
+
{({ feature, plan, index }) => (
|
|
2501
|
+
<li key={feature.id}>
|
|
2502
|
+
{feature.displayName}
|
|
2503
|
+
</li>
|
|
2504
|
+
)}
|
|
2505
|
+
</KQFeatureList>
|
|
2506
|
+
```
|
|
2507
|
+
|
|
2508
|
+
| Prop | Type | Description |
|
|
2509
|
+
|---|---|---|
|
|
2510
|
+
| `planIdentifier` | `string` | The plan to list features for |
|
|
2511
|
+
| `featureType` | `'BOOLEAN' \| 'METER'` | Optional filter by feature type |
|
|
2512
|
+
| `loadingComponent` | `ReactNode` | Shown while data loads |
|
|
2513
|
+
| `fallback` | `ReactNode` | Shown when plan not found or no features match |
|
|
2514
|
+
| `children` | `(data) => ReactNode` | Render prop called for each enabled feature |
|
|
2515
|
+
|
|
2516
|
+
##### `kqFormatPrice()` — Price Formatter Utility
|
|
2517
|
+
|
|
2518
|
+
Standalone utility for formatting a numeric amount with a currency symbol:
|
|
2519
|
+
|
|
2520
|
+
```ts
|
|
2521
|
+
import { kqFormatPrice } from '@kelviq/react-sdk';
|
|
2522
|
+
|
|
2523
|
+
kqFormatPrice(9.99, '$', { pricingLocale: 'en-US' }); // "$9.99"
|
|
2524
|
+
kqFormatPrice(1200, '€', { compact: true, pricingLocale: 'de-DE' }); // "€1,2K"
|
|
2525
|
+
kqFormatPrice(0, '$', { includeCurrencySymbol: false }); // "0"
|
|
2526
|
+
```
|
|
2527
|
+
|
|
2528
|
+
| Option | Type | Default | Description |
|
|
2529
|
+
|---|---|---|---|
|
|
2530
|
+
| `compact` | `boolean` | `false` | Use compact notation (e.g. `1.2K`) |
|
|
2531
|
+
| `locale` | `string` | `pricingLocale` | Override locale for number formatting |
|
|
2532
|
+
| `pricingLocale` | `string` | `'en-US'` | Locale from the pricing API |
|
|
2533
|
+
| `includeCurrencySymbol` | `boolean` | `true` | Prepend the currency symbol |
|
|
2534
|
+
|
|
2535
|
+
##### New Types
|
|
2536
|
+
|
|
2537
|
+
```ts
|
|
2538
|
+
RawPricingFeature
|
|
2539
|
+
RawPricingCharge
|
|
2540
|
+
RawPricingPrice
|
|
2541
|
+
RawPricingPlan
|
|
2542
|
+
RawPricingBillingPeriod
|
|
2543
|
+
RawPricingApiResponse
|
|
2544
|
+
|
|
2545
|
+
KQFormatPriceOptions
|
|
2546
|
+
KQPriceProps
|
|
2547
|
+
KQFeatureListProps
|
|
2548
|
+
```
|
|
2549
|
+
|
|
2550
|
+
##### New Exports
|
|
2551
|
+
|
|
2552
|
+
```ts
|
|
2553
|
+
export { usePricing } from './hooks/usePricing';
|
|
2554
|
+
export { KQPrice } from './components/KQPrice';
|
|
2555
|
+
export { KQFeatureList } from './components/KQFeatureList';
|
|
2556
|
+
export { kqFormatPrice } from './utils/formatPrice';
|
|
2557
|
+
export type * from './types/api.types';
|
|
2558
|
+
```
|
|
2559
|
+
|
|
2560
|
+
</Update>
|
|
2561
|
+
|
|
2562
|
+
<Update label="v0.0.4" description="May 7, 2026" tags={["JS Promotions UI"]}>
|
|
2563
|
+
|
|
2564
|
+
### Changed
|
|
2565
|
+
|
|
2566
|
+
#### Close Icon Update
|
|
2567
|
+
The close icon across all promotion UI components has been updated for better visibility and brand alignment. This change ensures a more consistent user experience when dismissing active promotions.
|
|
2568
|
+
|
|
2569
|
+
</Update>
|
|
2570
|
+
|
|
2571
|
+
<Update label="v1.1.0" description="May 7, 2026" tags={["API"]}>
|
|
2572
|
+
|
|
2573
|
+
### New Features
|
|
2574
|
+
|
|
2575
|
+
#### Enhanced Checkout Configuration
|
|
2576
|
+
You can now pass additional configuration parameters when [creating a checkout session via the API](https://docs.kelviq.com/api-reference/checkout/create-a-checkout-session). These new fields allow for tighter control over the customer experience:
|
|
2577
|
+
|
|
2578
|
+
* **`lockEmail`**: When set to `true`, the email address field on the checkout page is disabled, preventing customers from changing the email associated with the session.
|
|
2579
|
+
* **`discountsEnabled`**: A boolean to explicitly allow or disallow discount code application on the checkout page.
|
|
2580
|
+
* **`defaultBillingCountry`**: Pre-fills the billing country field (e.g., `"IN"`).
|
|
2581
|
+
|
|
2582
|
+
**Example Payload:**
|
|
2583
|
+
|
|
2584
|
+
```json
|
|
2585
|
+
{
|
|
2586
|
+
"planIdentifier": "base",
|
|
2587
|
+
"successUrl": "[https://kelviq.com/checkout/success](https://kelviq.com/checkout/success)",
|
|
2588
|
+
"chargePeriod": "MONTHLY",
|
|
2589
|
+
"customerId": "sachin",
|
|
2590
|
+
"lockEmail": true,
|
|
2591
|
+
"discountsEnabled": false,
|
|
2592
|
+
"defaultBillingCountry": "IN"
|
|
2593
|
+
}
|
|
2594
|
+
```
|
|
2595
|
+
|
|
2596
|
+
</Update>
|
|
2597
|
+
|
|
2598
|
+
<Update label="v1.0.0" description="May 7, 2026" tags={["API"]}>
|
|
2599
|
+
|
|
2600
|
+
### New Features
|
|
2601
|
+
|
|
2602
|
+
#### Custom Dynamic Amount Support
|
|
2603
|
+
Added support for custom dynamic amounts on the checkout page. You can now pass a specific `custom_amount` directly via the checkout API, which is ideal for usage-based, variable, or custom-quoted pricing models.
|
|
2604
|
+
|
|
2605
|
+
* **`custom_amount`**: The specific numeric amount to be charged to the customer. This overrides static plan pricing and is ideal for usage-based, variable, or custom-quoted pricing models.
|
|
2606
|
+
|
|
2607
|
+
* **`tax_behavior`**: Specifies how taxes should be applied to the custom amount. For example, setting it to "INCLUSIVE" means the tax is already factored into the custom_amount, while "EXCLUSIVE" would add the tax on top of the base amount.
|
|
2608
|
+
|
|
2609
|
+
* **`currency_code`**: The three-letter ISO currency code (e.g., "INR", "USD") that defines the currency in which the custom_amount should be processed.
|
|
2610
|
+
|
|
2611
|
+
```json
|
|
2612
|
+
{
|
|
2613
|
+
"planIdentifier": "automatic-pricing",
|
|
2614
|
+
"successUrl": "[https://www.kelviq.com/](https://www.kelviq.com/)",
|
|
2615
|
+
"chargePeriod": "MONTHLY",
|
|
2616
|
+
"customerId": "sam-altman0010",
|
|
2617
|
+
"custom_amount": 1200,
|
|
2618
|
+
"tax_behavior": "INCLUSIVE",
|
|
2619
|
+
"currency_code": "INR"
|
|
2620
|
+
}
|
|
2621
|
+
```
|
|
2622
|
+
|
|
2623
|
+
</Update>
|
|
2624
|
+
|
|
2625
|
+
<Update label="v1.4" description="May 04, 2026" tags={["App"]}>
|
|
2626
|
+
|
|
2627
|
+
### Platform Improvements
|
|
2628
|
+
- **Webhook Enhancements** — New webhook options in settings, including **Webhook Logs** for easier debugging and a new **Plan Changed** webhook event.
|
|
2629
|
+
- **Analytics Refresh** — The analytics dashboard has a fresh new look for better data visualization and clarity.
|
|
2630
|
+
- **Early Payout Access** — The Payouts tab is now enabled even before business verification is complete, allowing you to prepare your financial setup easily.
|
|
2631
|
+
|
|
2632
|
+
### Fixes
|
|
2633
|
+
- **File Uploads** — Resolved an issue that caused duplicate files to be created during multiple file uploads.
|
|
2634
|
+
|
|
2635
|
+
</Update>
|
|
2636
|
+
|
|
2637
|
+
<Update label="v2.4.0" description="May 4, 2026" tags={["Node SDK"]}>
|
|
2638
|
+
|
|
2639
|
+
### New Features
|
|
2640
|
+
|
|
2641
|
+
#### Checkout Session — New Optional Parameters
|
|
2642
|
+
|
|
2643
|
+
Three new optional fields on `CreateCheckoutSessionPayload` give you more control over the hosted checkout page.
|
|
2644
|
+
|
|
2645
|
+
**`discountsEnabled`** — controls whether the coupon/discount code field is shown. Defaults to `true`.
|
|
2646
|
+
|
|
2647
|
+
**`lockEmail`** — when `true`, the email field is pre-filled and locked so the customer cannot change it. Defaults to `false`.
|
|
2648
|
+
|
|
2649
|
+
**`defaultBillingCountry`** — ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`) used to pre-fill the billing address country field.
|
|
2650
|
+
|
|
2651
|
+
```typescript
|
|
2652
|
+
const response = await client.checkout.createSession({
|
|
2653
|
+
planIdentifier: "plan-pro-monthly",
|
|
2654
|
+
chargePeriod: "MONTHLY",
|
|
2655
|
+
customerId: "cust_789",
|
|
2656
|
+
successUrl: "https://example.com/success",
|
|
2657
|
+
discountsEnabled: false,
|
|
2658
|
+
lockEmail: true,
|
|
2659
|
+
defaultBillingCountry: "US",
|
|
2660
|
+
});
|
|
2661
|
+
```
|
|
2662
|
+
|
|
2663
|
+
</Update>
|
|
2664
|
+
|
|
2665
|
+
<Update label="v2.4.0" description="May 4, 2026" tags={["Python SDK"]}>
|
|
2666
|
+
|
|
2667
|
+
### New Features
|
|
2668
|
+
|
|
2669
|
+
#### Checkout Session — New Optional Parameters
|
|
2670
|
+
|
|
2671
|
+
Three new optional parameters on `checkout.create_session()` give you more control over the hosted checkout page.
|
|
2672
|
+
|
|
2673
|
+
**`discounts_enabled`** — controls whether the coupon/discount code field is shown. Defaults to `True` on the server.
|
|
2674
|
+
|
|
2675
|
+
**`lock_email`** — when `True`, the email field is pre-filled and locked so the customer cannot change it. Defaults to `False`.
|
|
2676
|
+
|
|
2677
|
+
**`default_billing_country`** — ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`) used to pre-fill the billing address country field.
|
|
2678
|
+
|
|
2679
|
+
```python
|
|
2680
|
+
response = client.checkout.create_session(
|
|
2681
|
+
planIdentifier="plan-pro-monthly",
|
|
2682
|
+
chargePeriod="MONTHLY",
|
|
2683
|
+
customerId="cust_789",
|
|
2684
|
+
successUrl="https://example.com/success",
|
|
2685
|
+
discountsEnabled=False,
|
|
2686
|
+
lockEmail=True,
|
|
2687
|
+
defaultBillingCountry="US",
|
|
2688
|
+
)
|
|
2689
|
+
```
|
|
2690
|
+
|
|
2691
|
+
**Async variant:**
|
|
2692
|
+
|
|
2693
|
+
```python
|
|
2694
|
+
response = await async_client.checkout.create_session(
|
|
2695
|
+
planIdentifier="plan-pro-monthly",
|
|
2696
|
+
chargePeriod="MONTHLY",
|
|
2697
|
+
customerId="cust_789",
|
|
2698
|
+
successUrl="https://example.com/success",
|
|
2699
|
+
discountsEnabled=False,
|
|
2700
|
+
lockEmail=True,
|
|
2701
|
+
defaultBillingCountry="US",
|
|
2702
|
+
)
|
|
2703
|
+
```
|
|
2704
|
+
|
|
2705
|
+
</Update>
|
|
2706
|
+
|
|
2707
|
+
<Update label="v2.3.0" description="April 25, 2026" tags={["Node SDK"]}>
|
|
2708
|
+
|
|
2709
|
+
### New Features
|
|
2710
|
+
|
|
2711
|
+
#### Webhook Verification
|
|
2712
|
+
|
|
2713
|
+
A new `validateEvent` helper lets you securely verify incoming webhook requests from Kelviq in one step. It validates the HMAC-SHA256 signature using the three headers Kelviq attaches to every webhook delivery, then returns the parsed event object.
|
|
2714
|
+
|
|
2715
|
+
```typescript
|
|
2716
|
+
import { validateEvent, WebhookVerificationError } from '@kelviq/node-sdk';
|
|
2717
|
+
import express from 'express';
|
|
2718
|
+
|
|
2719
|
+
const app = express();
|
|
2720
|
+
|
|
2721
|
+
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
|
|
2722
|
+
try {
|
|
2723
|
+
const event = validateEvent(
|
|
2724
|
+
req.body,
|
|
2725
|
+
req.headers,
|
|
2726
|
+
'<YOUR_WEBHOOK_SECRET>',
|
|
2727
|
+
);
|
|
2728
|
+
|
|
2729
|
+
// Process the event
|
|
2730
|
+
console.log('Event type:', event.type);
|
|
2731
|
+
|
|
2732
|
+
res.sendStatus(202);
|
|
2733
|
+
} catch (err) {
|
|
2734
|
+
if (err instanceof WebhookVerificationError) {
|
|
2735
|
+
return res.sendStatus(403);
|
|
2736
|
+
}
|
|
2737
|
+
throw err;
|
|
2738
|
+
}
|
|
2739
|
+
});
|
|
2740
|
+
```
|
|
2741
|
+
|
|
2742
|
+
**`validateEvent(payload, headers, secret)`**
|
|
2743
|
+
|
|
2744
|
+
- `payload` — Raw request body as a `string` or `Buffer`. Must be the unparsed body — do not pass a pre-parsed JSON object.
|
|
2745
|
+
- `headers` — The request headers object (e.g. `req.headers` in Express). Header lookup is case-insensitive.
|
|
2746
|
+
- `secret` — Your webhook signing secret (`kq_whsec_...`) from the Kelviq dashboard.
|
|
2747
|
+
|
|
2748
|
+
Returns the parsed event as `Record<string, unknown>`. Throws `WebhookVerificationError` if a required header is missing, the signature format is invalid, or the signature does not match.
|
|
2749
|
+
|
|
2750
|
+
#### `WebhookVerificationError`
|
|
2751
|
+
|
|
2752
|
+
New error class thrown by `validateEvent` when verification fails. Extends `Error`.
|
|
2753
|
+
|
|
2754
|
+
</Update>
|
|
2755
|
+
|
|
2756
|
+
<Update label="v2.3.0" description="April 25, 2026" tags={["Python SDK"]}>
|
|
2757
|
+
|
|
2758
|
+
### New Features
|
|
2759
|
+
|
|
2760
|
+
#### Webhook Verification
|
|
2761
|
+
|
|
2762
|
+
A new `validate_event` helper lets you securely verify incoming webhook requests from Kelviq in one step. It validates the HMAC-SHA256 signature using the three headers Kelviq attaches to every webhook delivery, then returns the parsed event dictionary.
|
|
2763
|
+
|
|
2764
|
+
```python
|
|
2765
|
+
from flask import Flask, request
|
|
2766
|
+
from kelviq_sdk import validate_event, WebhookVerificationError
|
|
2767
|
+
|
|
2768
|
+
app = Flask(__name__)
|
|
2769
|
+
|
|
2770
|
+
@app.route('/webhook', methods=['POST'])
|
|
2771
|
+
def webhook():
|
|
2772
|
+
try:
|
|
2773
|
+
event = validate_event(
|
|
2774
|
+
payload=request.data,
|
|
2775
|
+
headers=request.headers,
|
|
2776
|
+
secret='<YOUR_WEBHOOK_SECRET>',
|
|
2777
|
+
)
|
|
2778
|
+
|
|
2779
|
+
# Process the event
|
|
2780
|
+
print('Event type:', event.get('type'))
|
|
2781
|
+
|
|
2782
|
+
return "", 202
|
|
2783
|
+
except WebhookVerificationError as e:
|
|
2784
|
+
return "", 403
|
|
2785
|
+
```
|
|
2786
|
+
|
|
2787
|
+
**`validate_event(payload, headers, secret)`**
|
|
2788
|
+
|
|
2789
|
+
- `payload` — Raw request body as `bytes` or `str`. Must be the unparsed body — do not pass a pre-parsed dictionary.
|
|
2790
|
+
- `headers` — Any mapping of header name to value (e.g. `request.headers` in Flask). Header lookup is case-insensitive.
|
|
2791
|
+
- `secret` — Your webhook signing secret (`kq_whsec_...`) from the Kelviq dashboard.
|
|
2792
|
+
|
|
2793
|
+
Returns the parsed event as `Dict[str, Any]`. Raises `WebhookVerificationError` if a required header is missing, the signature format is invalid, or the signature does not match.
|
|
2794
|
+
|
|
2795
|
+
#### `WebhookVerificationError`
|
|
2796
|
+
|
|
2797
|
+
New exception class raised by `validate_event` when verification fails. Extends `Exception`.
|
|
2798
|
+
|
|
2799
|
+
</Update>
|
|
2800
|
+
|
|
2801
|
+
<Update label="v1.3" description="April 22, 2026" tags={["App"]}>
|
|
2802
|
+
|
|
2803
|
+
### New Features
|
|
2804
|
+
- **Promotions** — A new framework for managing promotional offers and campaigns directly within the dashboard.
|
|
2805
|
+
- **Tax Information in Transactions** — Detailed tax breakdowns are now included in transaction records, providing full transparency for accounting.
|
|
2806
|
+
- **Zapier Integration** — Connect Kelviq with thousands of other apps. Automate your workflow by triggering actions in external tools whenever a subscription or payment event occurs.
|
|
2807
|
+
|
|
2808
|
+
</Update>
|
|
2809
|
+
|
|
2810
|
+
<Update label="v2.2.0" description="April 13, 2026" tags={["Node SDK"]}>
|
|
2811
|
+
|
|
2812
|
+
### New Features
|
|
2813
|
+
|
|
2814
|
+
#### License Management Module
|
|
2815
|
+
|
|
2816
|
+
A new `client.license` module provides full lifecycle management for software licenses.
|
|
2817
|
+
|
|
2818
|
+
**`license.activate({ licenseKey, customerId?, instanceName?, metadata? })`**
|
|
2819
|
+
|
|
2820
|
+
Activates a license key and creates a new instance. Returns a `LicenseActivateResponse` containing the `instanceId`, `activatedAt`, `expiresOn`, and the full `LicenseDetails` object.
|
|
2821
|
+
|
|
2822
|
+
```typescript
|
|
2823
|
+
const response = await client.license.activate({
|
|
2824
|
+
licenseKey: "LIC-XXXX-YYYY-ZZZZ",
|
|
2825
|
+
customerId: "cust_789",
|
|
2826
|
+
instanceName: "My MacBook Pro",
|
|
2827
|
+
metadata: { os: "macOS", arch: "arm64" },
|
|
2828
|
+
});
|
|
2829
|
+
|
|
2830
|
+
console.log(response.instanceId);
|
|
2831
|
+
console.log(response.license.activationUsage); // e.g. 1
|
|
2832
|
+
console.log(response.license.plan.product.name); // e.g. "Kelviq Engine"
|
|
2833
|
+
```
|
|
2834
|
+
|
|
2835
|
+
**`license.deactivate({ licenseKey, instanceId })`**
|
|
2836
|
+
|
|
2837
|
+
Deactivates a specific license instance. Returns a `LicenseDeactivateResponse` with `message` and `deactivatedAt`.
|
|
2838
|
+
|
|
2839
|
+
```typescript
|
|
2840
|
+
const response = await client.license.deactivate({
|
|
2841
|
+
licenseKey: "LIC-XXXX-YYYY-ZZZZ",
|
|
2842
|
+
instanceId: "8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
|
|
2843
|
+
});
|
|
2844
|
+
console.log(response.message); // "License instance deactivated successfully."
|
|
2845
|
+
```
|
|
2846
|
+
|
|
2847
|
+
**`license.validate({ licenseKey, instanceId? })`**
|
|
2848
|
+
|
|
2849
|
+
Validates a license key and optionally a specific instance. Returns a `LicenseValidateResponse` with `valid`, `code`, `detail`, `metadata`, and the full `LicenseDetails`.
|
|
2850
|
+
|
|
2851
|
+
```typescript
|
|
2852
|
+
const response = await client.license.validate({
|
|
2853
|
+
licenseKey: "LIC-XXXX-YYYY-ZZZZ",
|
|
2854
|
+
instanceId: "8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
|
|
2855
|
+
});
|
|
2856
|
+
|
|
2857
|
+
if (response.valid) {
|
|
2858
|
+
console.log(`Valid — code: ${response.code}`);
|
|
2859
|
+
} else {
|
|
2860
|
+
console.log(`Invalid — ${response.detail}`);
|
|
2861
|
+
}
|
|
2862
|
+
```
|
|
2863
|
+
|
|
2864
|
+
#### New TypeScript Interfaces
|
|
2865
|
+
|
|
2866
|
+
- **`LicenseDetails`** — Full license object with `id`, `licenseKey`, `activatedOn`, `expiresOn`, `activationUsage`, `activationLimit`, `enabled`, `customer`, `plan`, and `subscription`.
|
|
2867
|
+
- **`LicenseCustomer`** — `{ customerId, name?, email? }` nested in `LicenseDetails`.
|
|
2868
|
+
- **`LicensePlan`** — Expanded with `description`, `version`, `isLatest`, and `product` (nested `LicensePlanProduct`).
|
|
2869
|
+
- **`LicensePlanProduct`** — `{ id, identifier, name, taxCode?, createdOn?, modifiedOn? }`.
|
|
2870
|
+
- **`LicenseActivateResponse`**, **`LicenseDeactivateResponse`**, **`LicenseValidateResponse`** — Typed responses for each operation.
|
|
2871
|
+
|
|
2872
|
+
#### `SubscriptionData` New Fields
|
|
2873
|
+
|
|
2874
|
+
Three new fields derived from the subscription's `recurrence` string are now included in `SubscriptionData` (returned within `LicenseDetails.subscription` and customer subscription summaries):
|
|
2875
|
+
|
|
2876
|
+
- **`billingType`** — `"SUBSCRIPTION"` if the plan has a recurrence, `"ONE_TIME"` otherwise.
|
|
2877
|
+
- **`recurrenceUnit`** — Integer unit from the recurrence string (e.g. `1` from `"1 month"`), or `null`.
|
|
2878
|
+
- **`recurrenceType`** — Recurrence period in uppercase (e.g. `"MONTH"`), or `null`.
|
|
2879
|
+
|
|
2880
|
+
</Update>
|
|
2881
|
+
|
|
2882
|
+
<Update label="v2.2.0" description="April 13, 2026" tags={["Python SDK"]}>
|
|
2883
|
+
|
|
2884
|
+
### New Features
|
|
2885
|
+
|
|
2886
|
+
#### License Management Module
|
|
2887
|
+
|
|
2888
|
+
A new `client.license` module provides full lifecycle management for software licenses. All methods are available in both synchronous and asynchronous clients.
|
|
2889
|
+
|
|
2890
|
+
**`license.activate(licenseKey, customerId?, instanceName?, metadata?)`**
|
|
2891
|
+
|
|
2892
|
+
Activates a license key and creates a new instance. Returns a `LicenseActivateResponse` (Pydantic model) containing the `instanceId`, `activatedAt`, `expiresOn`, and the full `LicenseDetails` object.
|
|
2893
|
+
|
|
2894
|
+
```python
|
|
2895
|
+
response = client.license.activate(
|
|
2896
|
+
licenseKey="LIC-XXXX-YYYY-ZZZZ",
|
|
2897
|
+
customerId="cust_789",
|
|
2898
|
+
instanceName="My MacBook Pro",
|
|
2899
|
+
metadata={"os": "macOS", "arch": "arm64"},
|
|
2900
|
+
)
|
|
2901
|
+
|
|
2902
|
+
print(response.instanceId)
|
|
2903
|
+
print(response.license.activationUsage) # e.g. 1
|
|
2904
|
+
print(response.license.plan.product.name) # e.g. "Kelviq Engine"
|
|
2905
|
+
print(response.license.subscription.billingType) # "SUBSCRIPTION"
|
|
2906
|
+
```
|
|
2907
|
+
|
|
2908
|
+
**`license.deactivate(licenseKey, instanceId)`**
|
|
2909
|
+
|
|
2910
|
+
Deactivates a specific license instance. Returns a `LicenseDeactivateResponse` with `message` and `deactivatedAt`.
|
|
2911
|
+
|
|
2912
|
+
```python
|
|
2913
|
+
response = client.license.deactivate(
|
|
2914
|
+
licenseKey="LIC-XXXX-YYYY-ZZZZ",
|
|
2915
|
+
instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
|
|
2916
|
+
)
|
|
2917
|
+
print(response.message) # "License instance deactivated successfully."
|
|
2918
|
+
```
|
|
2919
|
+
|
|
2920
|
+
**`license.validate(licenseKey, instanceId?)`**
|
|
2921
|
+
|
|
2922
|
+
Validates a license key and optionally a specific instance. Returns a `LicenseValidateResponse` with `valid`, `code`, `detail`, `metadata`, and the full `LicenseDetails`.
|
|
2923
|
+
|
|
2924
|
+
```python
|
|
2925
|
+
response = client.license.validate(
|
|
2926
|
+
licenseKey="LIC-XXXX-YYYY-ZZZZ",
|
|
2927
|
+
instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
|
|
2928
|
+
)
|
|
2929
|
+
|
|
2930
|
+
if response.valid:
|
|
2931
|
+
print(f"Valid — code: {response.code}")
|
|
2932
|
+
else:
|
|
2933
|
+
print(f"Invalid — {response.detail}")
|
|
2934
|
+
```
|
|
2935
|
+
|
|
2936
|
+
#### New Pydantic Models
|
|
2937
|
+
|
|
2938
|
+
- **`LicenseDetails`** — Full license object with `id`, `licenseKey`, `activatedOn`, `expiresOn`, `activationUsage`, `activationLimit`, `enabled`, `customer`, `plan`, and `subscription`.
|
|
2939
|
+
- **`LicenseCustomer`** — `customerId`, `name`, `email` nested within `LicenseDetails`.
|
|
2940
|
+
- **`LicensePlan`** — Expanded with `description`, `version`, `isLatest`, and `product` (nested `LicensePlanProduct` model).
|
|
2941
|
+
- **`LicensePlanProduct`** — `id`, `identifier`, `name`, `taxCode`, `createdOn`, `modifiedOn`.
|
|
2942
|
+
- **`LicenseActivateResponse`**, **`LicenseDeactivateResponse`**, **`LicenseValidateResponse`** — Typed Pydantic response models for each operation.
|
|
2943
|
+
|
|
2944
|
+
#### `SubscriptionData` New Fields
|
|
2945
|
+
|
|
2946
|
+
Three new fields derived from the subscription's `recurrence` string are now included in `SubscriptionData` (returned within `LicenseDetails.subscription` and customer subscription summaries):
|
|
2947
|
+
|
|
2948
|
+
- **`billingType`** — `"SUBSCRIPTION"` if the plan has a recurrence, `"ONE_TIME"` otherwise.
|
|
2949
|
+
- **`recurrenceUnit`** — Integer unit from the recurrence string (e.g. `1` from `"1 month"`), or `None`.
|
|
2950
|
+
- **`recurrenceType`** — Recurrence period in uppercase (e.g. `"MONTH"`), or `None`.
|
|
2951
|
+
|
|
2952
|
+
</Update>
|
|
2953
|
+
|
|
2954
|
+
<Update label="v1.2" description="April 10, 2026" tags={["App"]}>
|
|
2955
|
+
|
|
2956
|
+
### Improvements
|
|
2957
|
+
- **Webhooks Foundation** — Added initial webhook configuration options within the settings menu to prepare for advanced automation.
|
|
2958
|
+
- **Product UI Refinement** — The entire product card is now clickable for faster navigation, and we've added field validation for regional pricing minimum values.
|
|
2959
|
+
|
|
2960
|
+
</Update>
|
|
2961
|
+
|
|
2962
|
+
<Update label="v2.1.0" description="April 2, 2026" tags={["Node SDK"]}>
|
|
2963
|
+
|
|
2964
|
+
### New Features
|
|
2965
|
+
|
|
2966
|
+
#### Customer Portal Module
|
|
2967
|
+
|
|
2968
|
+
A new `client.portal` module lets you create pre-authenticated customer portal sessions server-side and redirect customers directly to their self-serve portal.
|
|
2969
|
+
|
|
2970
|
+
**`portal.createSession({ customerId })`**
|
|
2971
|
+
|
|
2972
|
+
```typescript
|
|
2973
|
+
const session = await client.portal.createSession({
|
|
2974
|
+
customerId: "cust_789",
|
|
2975
|
+
});
|
|
2976
|
+
|
|
2977
|
+
// Redirect the customer — no login required
|
|
2978
|
+
res.redirect(session.customerPortalUrl);
|
|
2979
|
+
```
|
|
2980
|
+
|
|
2981
|
+
Returns `CreatePortalSessionResponse` with:
|
|
2982
|
+
|
|
2983
|
+
- `token` — Session token authenticating the portal session.
|
|
2984
|
+
- `email` — The customer's email address.
|
|
2985
|
+
- `customerPortalUrl` — Pre-authenticated URL to redirect the customer to.
|
|
2986
|
+
|
|
2987
|
+
</Update>
|
|
2988
|
+
|
|
2989
|
+
<Update label="v2.1.0" description="April 2, 2026" tags={["Python SDK"]}>
|
|
2990
|
+
|
|
2991
|
+
### New Features
|
|
2992
|
+
|
|
2993
|
+
#### Customer Portal Module
|
|
2994
|
+
|
|
2995
|
+
A new `client.portal` module lets you create pre-authenticated customer portal sessions server-side and redirect customers directly to their self-serve portal. Available on both synchronous and asynchronous clients.
|
|
2996
|
+
|
|
2997
|
+
**`portal.create_session(customerId)`**
|
|
2998
|
+
|
|
2999
|
+
```python
|
|
3000
|
+
session = client.portal.create_session(customerId="cust_789")
|
|
3001
|
+
|
|
3002
|
+
# Redirect your customer — no login required
|
|
3003
|
+
print(session.customerPortalUrl)
|
|
3004
|
+
```
|
|
3005
|
+
|
|
3006
|
+
**Async variant:**
|
|
3007
|
+
|
|
3008
|
+
```python
|
|
3009
|
+
session = await async_client.portal.create_session(customerId="cust_789")
|
|
3010
|
+
```
|
|
3011
|
+
|
|
3012
|
+
Returns `CreatePortalSessionResponse` (Pydantic model) with:
|
|
3013
|
+
|
|
3014
|
+
- `token` (str) — Session token authenticating the portal session.
|
|
3015
|
+
- `email` (str) — The customer's email address.
|
|
3016
|
+
- `customerPortalUrl` (str) — Pre-authenticated URL to redirect the customer to.
|
|
3017
|
+
|
|
3018
|
+
</Update>
|
|
3019
|
+
|
|
3020
|
+
<Update label="v1.1" description="February 27, 2026" tags={["App"]}>
|
|
3021
|
+
|
|
3022
|
+
### New Features
|
|
3023
|
+
|
|
3024
|
+
- **Multiple subscriptions per customer** — Kelviq now supports customers having multiple active subscriptions. Use this to set up add-ons, credit packs, or top-ups alongside a base plan. Our SDKs automatically aggregate entitlements across all subscriptions, so your app always sees the correct combined usage and limits.
|
|
3025
|
+
- **New Subscriptions page** — A dedicated page to view and manage all subscriptions in one place.
|
|
3026
|
+
- **New Payout Details page** — View detailed breakdowns for individual payouts.
|
|
3027
|
+
- **Transactions & Details page under Payouts** — Browse all payout transactions with a detail view for each entry.
|
|
3028
|
+
- **Discount coupons on checkout URLs** — You can now attach discount coupons directly to checkout URLs, allowing you to share pre-discounted links with customers.
|
|
3029
|
+
- **Block size 1 for package pricing** — Package pricing now supports a block size of 1, giving you more granular control over package-based plans.
|
|
3030
|
+
- **Updated Publish modal UI** — The publish modal has been redesigned for a cleaner, more intuitive experience.
|
|
3031
|
+
|
|
3032
|
+
### Improvements
|
|
3033
|
+
|
|
3034
|
+
- **Flat & package pricing for one-time charges** — Flat-rate and package pricing models are now available for one-time products, not just recurring plans.
|
|
3035
|
+
- **Copy charge period on hover** — Hover over a charge period in the pricing section to quickly copy it to your clipboard.
|
|
3036
|
+
- **Plan details page UI improvements** — The plan details page has been refreshed with a cleaner layout and better readability.
|
|
3037
|
+
- **Improved refund error messages** — Refund errors now include clearer descriptions to help you understand what went wrong.
|
|
3038
|
+
- **Improved Analytics UI** — The analytics dashboard has been updated with a more polished interface.
|
|
3039
|
+
- **Download invoice in subscription detail page** — You can now download invoices directly from any subscription's detail page.
|
|
3040
|
+
- **Cancel subscription from customer detail page** — Added the ability to cancel a customer's subscription directly from their detail page without navigating away.
|
|
3041
|
+
|
|
3042
|
+
### Fixes
|
|
3043
|
+
|
|
3044
|
+
- **Entitlements override indicator** — Fixed an issue where entitlements were incorrectly shown as "overridden" in the UI when the values hadn't actually changed during feature copying.
|
|
3045
|
+
- **Refund button disabled when not applicable** — The refund payment button is now correctly disabled when a payment has already been refunded or the subscription is in a trial period.
|
|
3046
|
+
- **Billing info badge for one-time orders** — Fixed the billing info badge not appearing for one-time orders in the order list and detail pages.
|
|
3047
|
+
|
|
3048
|
+
</Update>
|
|
3049
|
+
|
|
3050
|
+
<Update label="v2.0.0" description="February 27, 2026" tags={["JS SDK"]}>
|
|
3051
|
+
|
|
3052
|
+
### New Features
|
|
3053
|
+
|
|
3054
|
+
#### Hybrid Aggregation Engine
|
|
3055
|
+
|
|
3056
|
+
If a customer has multiple subscriptions (e.g., a base plan + a top-up), the API may return duplicate `featureId` entries. The SDK now automatically aggregates them into a single `Entitlement` object per feature — no manual merging required.
|
|
3057
|
+
|
|
3058
|
+
**Aggregation rules:**
|
|
3059
|
+
|
|
3060
|
+
| Feature Type | `hasAccess` | `currentUsage` | `usageLimit` | `hardLimit` |
|
|
3061
|
+
|---|---|---|---|---|
|
|
3062
|
+
| **METER** | `true` if `remaining > 0` or unlimited | Summed | Summed | `true` if any item sets it |
|
|
3063
|
+
| **BOOLEAN** | `true` if any item grants access | `0` | `null` | `false` |
|
|
3064
|
+
| **CUSTOMIZABLE** | `true` if any item grants access | First item's value | First item's value | First item's value |
|
|
3065
|
+
|
|
3066
|
+
Per-item details (like `resetAt` and individual `hardLimit` values) are available on `entitlement.items[]`.
|
|
3067
|
+
|
|
3068
|
+
#### `getEntitlements()` — Fetch All Entitlements
|
|
3069
|
+
|
|
3070
|
+
Returns all aggregated entitlements as a map keyed by `featureId`. Replaces the old `getAllEntitlements()` method.
|
|
3071
|
+
|
|
3072
|
+
```typescript
|
|
3073
|
+
const entitlements = kq.getEntitlements();
|
|
3074
|
+
// { "email-sends": Entitlement, "api-calls": Entitlement, ... }
|
|
3075
|
+
```
|
|
3076
|
+
|
|
3077
|
+
#### `getRawEntitlement(featureId)` — Raw Data for a Single Feature
|
|
3078
|
+
|
|
3079
|
+
Returns the un-aggregated raw API items for a specific `featureId`. Useful when you need per-subscription details.
|
|
3080
|
+
|
|
3081
|
+
```typescript
|
|
3082
|
+
const rawItems = kq.getRawEntitlement("email-sends");
|
|
3083
|
+
// [{ featureId: 'email-sends', featureType: 'METER', hasAccess: true, ... }, ...]
|
|
3084
|
+
```
|
|
3085
|
+
|
|
3086
|
+
#### `getRawEntitlements()` — Full Raw API Response
|
|
3087
|
+
|
|
3088
|
+
Returns the complete raw API response including the `customerId` wrapper, before any aggregation.
|
|
3089
|
+
|
|
3090
|
+
```typescript
|
|
3091
|
+
const raw = kq.getRawEntitlements();
|
|
3092
|
+
// { customerId: 'cust_123', entitlements: [...] }
|
|
3093
|
+
```
|
|
3094
|
+
|
|
3095
|
+
#### `ready()` — Wait for Initial Fetch
|
|
3096
|
+
|
|
3097
|
+
Returns a promise that resolves once the initial entitlement fetch completes. If `initializeAndFetch` was not set, resolves immediately.
|
|
3098
|
+
|
|
3099
|
+
```typescript
|
|
3100
|
+
const kq = kelviqSDK({
|
|
3101
|
+
customerId: "cust_123",
|
|
3102
|
+
accessToken: "your-access-token",
|
|
3103
|
+
});
|
|
3104
|
+
|
|
3105
|
+
await kq.ready();
|
|
3106
|
+
// Entitlements are now available
|
|
3107
|
+
const emails = kq.getEntitlement("email-sends");
|
|
3108
|
+
console.log(emails.hasAccess, emails.remaining);
|
|
3109
|
+
```
|
|
3110
|
+
|
|
3111
|
+
#### New Type Exports
|
|
3112
|
+
|
|
3113
|
+
`RawEntitlement` and `RawEntitlementsApiResponse` are now exported for consumers who need to type the raw API objects in their own code.
|
|
3114
|
+
|
|
3115
|
+
---
|
|
3116
|
+
|
|
3117
|
+
### Breaking Changes
|
|
3118
|
+
|
|
3119
|
+
#### Unified `Entitlement` Interface
|
|
3120
|
+
|
|
3121
|
+
The separate `BooleanEntitlement`, `ConfigEntitlement`, and `MeteredEntitlement` types have been replaced with a single, unified `Entitlement` interface:
|
|
3122
|
+
|
|
3123
|
+
```typescript
|
|
3124
|
+
interface Entitlement {
|
|
3125
|
+
featureId: string;
|
|
3126
|
+
featureType: "METER" | "BOOLEAN" | "CUSTOMIZABLE";
|
|
3127
|
+
hasAccess: boolean; // true if at least one item grants access
|
|
3128
|
+
hardLimit: boolean; // true if any item has hardLimit set
|
|
3129
|
+
currentUsage: number; // SUM of all items' currentUsage (METER only)
|
|
3130
|
+
usageLimit: number | null; // SUM of all items' usageLimit (METER only)
|
|
3131
|
+
remaining: number | null; // usageLimit - currentUsage
|
|
3132
|
+
items: RawEntitlement[]; // Original API objects for this featureId
|
|
3133
|
+
}
|
|
3134
|
+
```
|
|
3135
|
+
|
|
3136
|
+
**Migration:** Replace all references to `BooleanEntitlement`, `ConfigEntitlement`, `MeteredEntitlement`, and `AnyEntitlement` with `Entitlement`.
|
|
3137
|
+
|
|
3138
|
+
#### `getEntitlement()` No Longer Accepts a Type Argument
|
|
3139
|
+
|
|
3140
|
+
The generic type parameter and second `type` argument have been removed. The SDK now determines the feature type automatically.
|
|
3141
|
+
|
|
3142
|
+
```typescript
|
|
3143
|
+
// Before
|
|
3144
|
+
const emailQuota = kq.getEntitlement<MeteredEntitlement>("email-sends", "metered");
|
|
3145
|
+
console.log(emailQuota.used, emailQuota.limit);
|
|
3146
|
+
|
|
3147
|
+
// After
|
|
3148
|
+
const emailQuota = kq.getEntitlement("email-sends");
|
|
3149
|
+
console.log(emailQuota.currentUsage, emailQuota.usageLimit);
|
|
3150
|
+
```
|
|
3151
|
+
|
|
3152
|
+
#### Renamed Fields
|
|
3153
|
+
|
|
3154
|
+
| Before | After | Notes |
|
|
3155
|
+
|---|---|---|
|
|
3156
|
+
| `used` | `currentUsage` | Aligned with the raw API field name |
|
|
3157
|
+
| `limit` | `usageLimit` | Aligned with the raw API field name |
|
|
3158
|
+
| `type` | `featureType` | Now uses uppercase API values (`"METER"`, `"BOOLEAN"`, `"CUSTOMIZABLE"`) |
|
|
3159
|
+
| `configuration` | _(removed)_ | No longer surfaced at the top level |
|
|
3160
|
+
| `resetAt` | _(removed)_ | Access via `entitlement.items[].resetAt` (may differ per subscription) |
|
|
3161
|
+
|
|
3162
|
+
#### Removed Exports
|
|
3163
|
+
|
|
3164
|
+
The following types are no longer exported:
|
|
3165
|
+
|
|
3166
|
+
- `BooleanEntitlement`, `ConfigEntitlement`, `MeteredEntitlement`, `AnyEntitlement`
|
|
3167
|
+
- `EntitlementMap` is now `Record<string, Entitlement>` (no union type)
|
|
3168
|
+
|
|
3169
|
+
#### `getAllEntitlements()` Removed
|
|
3170
|
+
|
|
3171
|
+
Use `getEntitlements()` instead, which returns the aggregated map.
|
|
3172
|
+
|
|
3173
|
+
---
|
|
3174
|
+
|
|
3175
|
+
### Changed
|
|
3176
|
+
|
|
3177
|
+
- **`fetchAllEntitlements()` deduplicates concurrent calls** — Instead of rejecting with "already in progress", it returns the same in-flight promise. This makes `initializeAndFetch: true` safely composable with `await fetchAllEntitlements()`.
|
|
3178
|
+
- **`fetchAllEntitlements()` stores raw data** — Now stores both the full raw API response and the aggregated cache internally.
|
|
3179
|
+
- **`clearCache()` clears raw data** — Now also clears the stored raw API response.
|
|
3180
|
+
|
|
3181
|
+
---
|
|
3182
|
+
|
|
3183
|
+
### Fixed
|
|
3184
|
+
|
|
3185
|
+
- **`initializeAndFetch: false` was ignored** — The factory used `||` instead of `??`, so passing `false` had no effect and entitlements were always fetched on initialization. Fixed to use nullish coalescing (`??`).
|
|
3186
|
+
- **Options table in documentation** — Filled in missing type values for `accessToken` (`string`) and `onError` (`(error: Error) => void`).
|
|
3187
|
+
|
|
3188
|
+
</Update>
|
|
3189
|
+
|
|
3190
|
+
<Update label="v2.0.0" description="February 27, 2026" tags={["React SDK"]}>
|
|
3191
|
+
### New Features
|
|
3192
|
+
|
|
3193
|
+
#### Duplicate `featureId` Aggregation
|
|
3194
|
+
|
|
3195
|
+
The SDK now handles customers with multiple subscriptions that grant entitlements to the same feature. Raw entries are grouped by `featureId` and aggregated automatically:
|
|
3196
|
+
|
|
3197
|
+
- **METER**: `usageLimit` and `currentUsage` are summed across entries; `remaining` is recalculated
|
|
3198
|
+
- **BOOLEAN / CUSTOMIZABLE**: `hasAccess` is OR'd across entries (any `true` → `true`)
|
|
3199
|
+
The raw un-aggregated entries are preserved in the `items` array on each `Entitlement`.
|
|
3200
|
+
|
|
3201
|
+
#### `getEntitlements()` — Convenience Accessor
|
|
3202
|
+
|
|
3203
|
+
Returns the aggregated entitlements map directly, without the `AsyncState` wrapper:
|
|
3204
|
+
|
|
3205
|
+
```ts
|
|
3206
|
+
const { getEntitlements } = useKelviq();
|
|
3207
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
3208
|
+
|
|
3209
|
+
const emailFeature = entitlements["email-sends"];
|
|
3210
|
+
console.log(emailFeature.hasAccess, emailFeature.remaining);
|
|
3211
|
+
```
|
|
3212
|
+
|
|
3213
|
+
#### `getRawEntitlements()` — Raw API Response
|
|
3214
|
+
|
|
3215
|
+
Access the un-aggregated API response with the `customerId` wrapper:
|
|
3216
|
+
|
|
3217
|
+
```ts
|
|
3218
|
+
const { getRawEntitlements } = useKelviq();
|
|
3219
|
+
const raw = getRawEntitlements();
|
|
3220
|
+
// { customerId: "cust_123", entitlements: [...] }
|
|
3221
|
+
```
|
|
3222
|
+
|
|
3223
|
+
#### `getRawEntitlement(featureId)` — Raw Data for a Single Feature
|
|
3224
|
+
|
|
3225
|
+
Returns the raw API response filtered to a specific featureId:
|
|
3226
|
+
|
|
3227
|
+
```ts
|
|
3228
|
+
const { getRawEntitlement } = useKelviq();
|
|
3229
|
+
const raw = getRawEntitlement("email-sends");
|
|
3230
|
+
// { customerId: "cust_123", entitlements: [/* only "email-sends" entries */] }
|
|
3231
|
+
```
|
|
3232
|
+
|
|
3233
|
+
#### `updateEntitlement()` — Client-Side Entitlement Mutation
|
|
3234
|
+
|
|
3235
|
+
Update an entitlement in-place, for example after recording a usage increment on the client side. The `remaining` field is automatically recalculated.
|
|
3236
|
+
|
|
3237
|
+
```ts
|
|
3238
|
+
const { updateEntitlement } = useKelviq();
|
|
3239
|
+
updateEntitlement("email-sends", { currentUsage: 5 });
|
|
3240
|
+
// `remaining` is automatically recalculated
|
|
3241
|
+
```
|
|
3242
|
+
|
|
3243
|
+
Accepts `Partial<Omit<Entitlement, 'featureId' | 'featureType' | 'items'>>`.
|
|
3244
|
+
|
|
3245
|
+
#### `environment` Prop on `KelviqProvider`
|
|
3246
|
+
|
|
3247
|
+
Supports `'production'` (default) and `'sandbox'`, which selects the appropriate default API URL:
|
|
3248
|
+
|
|
3249
|
+
```tsx
|
|
3250
|
+
<KelviqProvider environment="sandbox" customerId="cust_123" accessToken="...">
|
|
3251
|
+
|
|
3252
|
+
</KelviqProvider>
|
|
3253
|
+
```
|
|
3254
|
+
|
|
3255
|
+
---
|
|
3256
|
+
|
|
3257
|
+
### Breaking Changes
|
|
3258
|
+
|
|
3259
|
+
#### Unified `Entitlement` Type
|
|
3260
|
+
|
|
3261
|
+
The three separate entitlement interfaces and their union type have been replaced by a single unified `Entitlement` interface:
|
|
3262
|
+
|
|
3263
|
+
```ts
|
|
3264
|
+
// Before — three separate types
|
|
3265
|
+
interface BooleanEntitlement { type: 'boolean'; featureKey: string; hasAccess: boolean; }
|
|
3266
|
+
interface ConfigEntitlement { type: 'customizable'; featureKey: string; hasAccess: boolean; configuration: number | null; }
|
|
3267
|
+
interface MeteredEntitlement { type: 'metered'; featureKey: string; hasAccess: boolean; limit: number | null; used: number; remaining: number | null; resetAt: string | null; hardLimit: boolean; }
|
|
3268
|
+
|
|
3269
|
+
// After — one unified type
|
|
3270
|
+
interface Entitlement {
|
|
3271
|
+
featureId: string;
|
|
3272
|
+
featureType: 'METER' | 'BOOLEAN' | 'CUSTOMIZABLE';
|
|
3273
|
+
hasAccess: boolean;
|
|
3274
|
+
currentUsage: number;
|
|
3275
|
+
usageLimit: number | null;
|
|
3276
|
+
remaining: number | null;
|
|
3277
|
+
hardLimit: boolean;
|
|
3278
|
+
items: AnyRawEntitlementData[];
|
|
3279
|
+
}
|
|
3280
|
+
```
|
|
3281
|
+
|
|
3282
|
+
#### `featureKey` Renamed to `featureId`
|
|
3283
|
+
|
|
3284
|
+
All props, parameters, and type fields now use `featureId` to match the backend API naming:
|
|
3285
|
+
|
|
3286
|
+
```tsx
|
|
3287
|
+
// Before
|
|
3288
|
+
<ShowWhenBooleanEntitled featureKey="my-feature">
|
|
3289
|
+
|
|
3290
|
+
</ShowWhenBooleanEntitled>
|
|
3291
|
+
|
|
3292
|
+
// After
|
|
3293
|
+
<ShowWhenBooleanEntitled featureId="my-feature">
|
|
3294
|
+
|
|
3295
|
+
</ShowWhenBooleanEntitled>
|
|
3296
|
+
```
|
|
3297
|
+
|
|
3298
|
+
#### `Config` Renamed to `Customizable`
|
|
3299
|
+
|
|
3300
|
+
| Before | After |
|
|
3301
|
+
|---|---|
|
|
3302
|
+
| `useConfigEntitlement` | `useCustomizableEntitlement` |
|
|
3303
|
+
| `ShowWhenConfigEntitled` | `ShowWhenCustomizableEntitled` |
|
|
3304
|
+
| `ConfigEntitlement` type | Unified `Entitlement` |
|
|
3305
|
+
|
|
3306
|
+
#### `type` Field Renamed to `featureType` with Uppercase Values
|
|
3307
|
+
|
|
3308
|
+
| Before | After |
|
|
3309
|
+
|---|---|
|
|
3310
|
+
| `type: 'boolean'` | `featureType: 'BOOLEAN'` |
|
|
3311
|
+
| `type: 'customizable'` | `featureType: 'CUSTOMIZABLE'` |
|
|
3312
|
+
| `type: 'metered'` | `featureType: 'METER'` |
|
|
3313
|
+
|
|
3314
|
+
#### `configuration` Field Removed
|
|
3315
|
+
|
|
3316
|
+
`ConfigEntitlement.configuration` has been removed. Customizable entitlements now use the same `usageLimit`, `currentUsage`, and `remaining` fields as metered entitlements.
|
|
3317
|
+
|
|
3318
|
+
#### Hooks Return `Entitlement | null` Directly
|
|
3319
|
+
|
|
3320
|
+
All entitlement hooks now return the entitlement object directly (or `null`) instead of an `AsyncState` wrapper. Use the top-level `isLoading` and `error` from `useKelviq()` for loading/error states.
|
|
3321
|
+
|
|
3322
|
+
```ts
|
|
3323
|
+
// Before
|
|
3324
|
+
const { data, isLoading, error } = useMeteredEntitlement("my-feature");
|
|
3325
|
+
if (isLoading) return ;
|
|
3326
|
+
console.log(data?.used);
|
|
3327
|
+
|
|
3328
|
+
// After
|
|
3329
|
+
const entitlement = useMeteredEntitlement("my-feature");
|
|
3330
|
+
const { isLoading, error } = useKelviq();
|
|
3331
|
+
if (isLoading) return ;
|
|
3332
|
+
console.log(entitlement?.currentUsage);
|
|
3333
|
+
```
|
|
3334
|
+
|
|
3335
|
+
#### `getEntitlement()` Simplified
|
|
3336
|
+
|
|
3337
|
+
The generic type parameter and second argument have been removed:
|
|
3338
|
+
|
|
3339
|
+
```ts
|
|
3340
|
+
// Before
|
|
3341
|
+
getEntitlement<MeteredEntitlement>("my-feature", "metered")
|
|
3342
|
+
|
|
3343
|
+
// After
|
|
3344
|
+
getEntitlement("my-feature") // returns Entitlement | null
|
|
3345
|
+
```
|
|
3346
|
+
|
|
3347
|
+
#### `hasAccess()` Returns `boolean` (Never `undefined`)
|
|
3348
|
+
|
|
3349
|
+
`hasAccess(featureId)` now returns `false` when data is unavailable instead of `undefined`. No need for nullish checks.
|
|
3350
|
+
|
|
3351
|
+
#### Metered Field Renames
|
|
3352
|
+
|
|
3353
|
+
| Before | After | Notes |
|
|
3354
|
+
|---|---|---|
|
|
3355
|
+
| `limit` | `usageLimit` | Aligned with the API |
|
|
3356
|
+
| `used` | `currentUsage` | Aligned with the API |
|
|
3357
|
+
| `resetAt` | _(removed)_ | Now per-item: `entitlement.items[].resetAt` |
|
|
3358
|
+
| `hardLimit` | `hardLimit` | Now aggregated: `true` if any item sets it |
|
|
3359
|
+
|
|
3360
|
+
#### `allEntitlements.data` Shape Changed
|
|
3361
|
+
|
|
3362
|
+
The map is now keyed by `featureId` (previously `featureKey`) and contains unified `Entitlement` objects. Use the new `getEntitlements()` convenience method:
|
|
3363
|
+
|
|
3364
|
+
```ts
|
|
3365
|
+
// Before
|
|
3366
|
+
const { allEntitlements } = useKelviq();
|
|
3367
|
+
const myFeature = allEntitlements.data?.["my-feature"]; // AnyEntitlement | undefined
|
|
3368
|
+
|
|
3369
|
+
// After
|
|
3370
|
+
const { getEntitlements } = useKelviq();
|
|
3371
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
3372
|
+
const myFeature = entitlements["my-feature"]; // Entitlement | undefined
|
|
3373
|
+
```
|
|
3374
|
+
|
|
3375
|
+
---
|
|
3376
|
+
|
|
3377
|
+
### Migration Checklist
|
|
3378
|
+
|
|
3379
|
+
1. Replace all `featureKey` props/params with `featureId`
|
|
3380
|
+
2. Replace `entitlement.type` with `entitlement.featureType` and update values to uppercase
|
|
3381
|
+
3. Replace `useConfigEntitlement` with `useCustomizableEntitlement`
|
|
3382
|
+
4. Replace `ShowWhenConfigEntitled` with `ShowWhenCustomizableEntitled`
|
|
3383
|
+
5. Replace `ConfigEntitlement.configuration` with `usageLimit` / `currentUsage` / `remaining`
|
|
3384
|
+
6. Update hook consumers: hooks now return `Entitlement | null` directly (not `AsyncState`)
|
|
3385
|
+
7. Remove type parameters from `getEntitlement()` calls
|
|
3386
|
+
8. Replace `limit` → `usageLimit`, `used` → `currentUsage`
|
|
3387
|
+
9. Replace `entitlement.resetAt` with `entitlement.items[].resetAt`
|
|
3388
|
+
10. Use `getEntitlements()` instead of `allEntitlements.data`
|
|
3389
|
+
11. Use `getRawEntitlements()` for un-aggregated API data
|
|
3390
|
+
</Update>
|
|
3391
|
+
|
|
3392
|
+
<Update label="v2.0.0" description="February 27, 2026" tags={["React SDK"]}>
|
|
3393
|
+
|
|
3394
|
+
### New Features
|
|
3395
|
+
|
|
3396
|
+
#### Duplicate `featureId` Aggregation
|
|
3397
|
+
|
|
3398
|
+
The SDK now handles customers with multiple subscriptions that grant entitlements to the same feature. Raw entries are grouped by `featureId` and aggregated automatically:
|
|
3399
|
+
|
|
3400
|
+
- **METER**: `usageLimit` and `currentUsage` are summed across entries; `remaining` is recalculated
|
|
3401
|
+
- **BOOLEAN / CUSTOMIZABLE**: `hasAccess` is OR'd across entries (any `true` → `true`)
|
|
3402
|
+
|
|
3403
|
+
The raw un-aggregated entries are preserved in the `items` array on each `Entitlement`.
|
|
3404
|
+
|
|
3405
|
+
#### `getEntitlements()` — Convenience Accessor
|
|
3406
|
+
|
|
3407
|
+
Returns the aggregated entitlements map directly, without the `AsyncState` wrapper:
|
|
3408
|
+
|
|
3409
|
+
```ts
|
|
3410
|
+
const { getEntitlements } = useKelviq();
|
|
3411
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
3412
|
+
|
|
3413
|
+
const emailFeature = entitlements["email-sends"];
|
|
3414
|
+
console.log(emailFeature.hasAccess, emailFeature.remaining);
|
|
3415
|
+
```
|
|
3416
|
+
|
|
3417
|
+
#### `getRawEntitlements()` — Raw API Response
|
|
3418
|
+
|
|
3419
|
+
Access the un-aggregated API response with the `customerId` wrapper:
|
|
3420
|
+
|
|
3421
|
+
```ts
|
|
3422
|
+
const { getRawEntitlements } = useKelviq();
|
|
3423
|
+
const raw = getRawEntitlements();
|
|
3424
|
+
// { customerId: "cust_123", entitlements: [...] }
|
|
3425
|
+
```
|
|
3426
|
+
|
|
3427
|
+
#### `getRawEntitlement(featureId)` — Raw Data for a Single Feature
|
|
3428
|
+
|
|
3429
|
+
Returns the raw API response filtered to a specific featureId:
|
|
3430
|
+
|
|
3431
|
+
```ts
|
|
3432
|
+
const { getRawEntitlement } = useKelviq();
|
|
3433
|
+
const raw = getRawEntitlement("email-sends");
|
|
3434
|
+
// { customerId: "cust_123", entitlements: [/* only "email-sends" entries */] }
|
|
3435
|
+
```
|
|
3436
|
+
|
|
3437
|
+
#### `updateEntitlement()` — Client-Side Entitlement Mutation
|
|
3438
|
+
|
|
3439
|
+
Update an entitlement in-place, for example after recording a usage increment on the client side. The `remaining` field is automatically recalculated.
|
|
3440
|
+
|
|
3441
|
+
```ts
|
|
3442
|
+
const { updateEntitlement } = useKelviq();
|
|
3443
|
+
updateEntitlement("email-sends", { currentUsage: 5 });
|
|
3444
|
+
// `remaining` is automatically recalculated
|
|
3445
|
+
```
|
|
3446
|
+
|
|
3447
|
+
Accepts `Partial<Omit<Entitlement, 'featureId' | 'featureType' | 'items'>>`.
|
|
3448
|
+
|
|
3449
|
+
#### `environment` Prop on `KelviqProvider`
|
|
3450
|
+
|
|
3451
|
+
Supports `'production'` (default) and `'sandbox'`, which selects the appropriate default API URL:
|
|
3452
|
+
|
|
3453
|
+
```tsx
|
|
3454
|
+
<KelviqProvider environment="sandbox" customerId="cust_123" accessToken="...">
|
|
3455
|
+
|
|
3456
|
+
</KelviqProvider>
|
|
3457
|
+
```
|
|
3458
|
+
|
|
3459
|
+
---
|
|
3460
|
+
|
|
3461
|
+
### Breaking Changes
|
|
3462
|
+
|
|
3463
|
+
#### Unified `Entitlement` Type
|
|
3464
|
+
|
|
3465
|
+
The three separate entitlement interfaces and their union type have been replaced by a single unified `Entitlement` interface:
|
|
3466
|
+
|
|
3467
|
+
```ts
|
|
3468
|
+
// Before — three separate types
|
|
3469
|
+
interface BooleanEntitlement { type: 'boolean'; featureKey: string; hasAccess: boolean; }
|
|
3470
|
+
interface ConfigEntitlement { type: 'customizable'; featureKey: string; hasAccess: boolean; configuration: number | null; }
|
|
3471
|
+
interface MeteredEntitlement { type: 'metered'; featureKey: string; hasAccess: boolean; limit: number | null; used: number; remaining: number | null; resetAt: string | null; hardLimit: boolean; }
|
|
3472
|
+
|
|
3473
|
+
// After — one unified type
|
|
3474
|
+
interface Entitlement {
|
|
3475
|
+
featureId: string;
|
|
3476
|
+
featureType: 'METER' | 'BOOLEAN' | 'CUSTOMIZABLE';
|
|
3477
|
+
hasAccess: boolean;
|
|
3478
|
+
currentUsage: number;
|
|
3479
|
+
usageLimit: number | null;
|
|
3480
|
+
remaining: number | null;
|
|
3481
|
+
hardLimit: boolean;
|
|
3482
|
+
items: AnyRawEntitlementData[];
|
|
3483
|
+
}
|
|
3484
|
+
```
|
|
3485
|
+
|
|
3486
|
+
#### `featureKey` Renamed to `featureId`
|
|
3487
|
+
|
|
3488
|
+
All props, parameters, and type fields now use `featureId` to match the backend API naming:
|
|
3489
|
+
|
|
3490
|
+
```tsx
|
|
3491
|
+
// Before
|
|
3492
|
+
<ShowWhenBooleanEntitled featureKey="my-feature">
|
|
3493
|
+
|
|
3494
|
+
</ShowWhenBooleanEntitled>
|
|
3495
|
+
|
|
3496
|
+
// After
|
|
3497
|
+
<ShowWhenBooleanEntitled featureId="my-feature">
|
|
3498
|
+
|
|
3499
|
+
</ShowWhenBooleanEntitled>
|
|
3500
|
+
```
|
|
3501
|
+
|
|
3502
|
+
#### `Config` Renamed to `Customizable`
|
|
3503
|
+
|
|
3504
|
+
| Before | After |
|
|
3505
|
+
|---|---|
|
|
3506
|
+
| `useConfigEntitlement` | `useCustomizableEntitlement` |
|
|
3507
|
+
| `ShowWhenConfigEntitled` | `ShowWhenCustomizableEntitled` |
|
|
3508
|
+
| `ConfigEntitlement` type | Unified `Entitlement` |
|
|
3509
|
+
|
|
3510
|
+
#### `type` Field Renamed to `featureType` with Uppercase Values
|
|
3511
|
+
|
|
3512
|
+
| Before | After |
|
|
3513
|
+
|---|---|
|
|
3514
|
+
| `type: 'boolean'` | `featureType: 'BOOLEAN'` |
|
|
3515
|
+
| `type: 'customizable'` | `featureType: 'CUSTOMIZABLE'` |
|
|
3516
|
+
| `type: 'metered'` | `featureType: 'METER'` |
|
|
3517
|
+
|
|
3518
|
+
#### `configuration` Field Removed
|
|
3519
|
+
|
|
3520
|
+
`ConfigEntitlement.configuration` has been removed. Customizable entitlements now use the same `usageLimit`, `currentUsage`, and `remaining` fields as metered entitlements.
|
|
3521
|
+
|
|
3522
|
+
#### Hooks Return `Entitlement | null` Directly
|
|
3523
|
+
|
|
3524
|
+
All entitlement hooks now return the entitlement object directly (or `null`) instead of an `AsyncState` wrapper. Use the top-level `isLoading` and `error` from `useKelviq()` for loading/error states.
|
|
3525
|
+
|
|
3526
|
+
```ts
|
|
3527
|
+
// Before
|
|
3528
|
+
const { data, isLoading, error } = useMeteredEntitlement("my-feature");
|
|
3529
|
+
if (isLoading) return ;
|
|
3530
|
+
console.log(data?.used);
|
|
3531
|
+
|
|
3532
|
+
// After
|
|
3533
|
+
const entitlement = useMeteredEntitlement("my-feature");
|
|
3534
|
+
const { isLoading, error } = useKelviq();
|
|
3535
|
+
if (isLoading) return ;
|
|
3536
|
+
console.log(entitlement?.currentUsage);
|
|
3537
|
+
```
|
|
3538
|
+
|
|
3539
|
+
#### `getEntitlement()` Simplified
|
|
3540
|
+
|
|
3541
|
+
The generic type parameter and second argument have been removed:
|
|
3542
|
+
|
|
3543
|
+
```ts
|
|
3544
|
+
// Before
|
|
3545
|
+
getEntitlement<MeteredEntitlement>("my-feature", "metered")
|
|
3546
|
+
|
|
3547
|
+
// After
|
|
3548
|
+
getEntitlement("my-feature") // returns Entitlement | null
|
|
3549
|
+
```
|
|
3550
|
+
|
|
3551
|
+
#### `hasAccess()` Returns `boolean` (Never `undefined`)
|
|
3552
|
+
|
|
3553
|
+
`hasAccess(featureId)` now returns `false` when data is unavailable instead of `undefined`. No need for nullish checks.
|
|
3554
|
+
|
|
3555
|
+
#### Metered Field Renames
|
|
3556
|
+
|
|
3557
|
+
| Before | After | Notes |
|
|
3558
|
+
|---|---|---|
|
|
3559
|
+
| `limit` | `usageLimit` | Aligned with the API |
|
|
3560
|
+
| `used` | `currentUsage` | Aligned with the API |
|
|
3561
|
+
| `resetAt` | _(removed)_ | Now per-item: `entitlement.items[].resetAt` |
|
|
3562
|
+
| `hardLimit` | `hardLimit` | Now aggregated: `true` if any item sets it |
|
|
3563
|
+
|
|
3564
|
+
#### `allEntitlements.data` Shape Changed
|
|
3565
|
+
|
|
3566
|
+
The map is now keyed by `featureId` (previously `featureKey`) and contains unified `Entitlement` objects. Use the new `getEntitlements()` convenience method:
|
|
3567
|
+
|
|
3568
|
+
```ts
|
|
3569
|
+
// Before
|
|
3570
|
+
const { allEntitlements } = useKelviq();
|
|
3571
|
+
const myFeature = allEntitlements.data?.["my-feature"]; // AnyEntitlement | undefined
|
|
3572
|
+
|
|
3573
|
+
// After
|
|
3574
|
+
const { getEntitlements } = useKelviq();
|
|
3575
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
3576
|
+
const myFeature = entitlements["my-feature"]; // Entitlement | undefined
|
|
3577
|
+
```
|
|
3578
|
+
|
|
3579
|
+
---
|
|
3580
|
+
|
|
3581
|
+
### Migration Checklist
|
|
3582
|
+
|
|
3583
|
+
1. Replace all `featureKey` props/params with `featureId`
|
|
3584
|
+
2. Replace `entitlement.type` with `entitlement.featureType` and update values to uppercase
|
|
3585
|
+
3. Replace `useConfigEntitlement` with `useCustomizableEntitlement`
|
|
3586
|
+
4. Replace `ShowWhenConfigEntitled` with `ShowWhenCustomizableEntitled`
|
|
3587
|
+
5. Replace `ConfigEntitlement.configuration` with `usageLimit` / `currentUsage` / `remaining`
|
|
3588
|
+
6. Update hook consumers: hooks now return `Entitlement | null` directly (not `AsyncState`)
|
|
3589
|
+
7. Remove type parameters from `getEntitlement()` calls
|
|
3590
|
+
8. Replace `limit` → `usageLimit`, `used` → `currentUsage`
|
|
3591
|
+
9. Replace `entitlement.resetAt` with `entitlement.items[].resetAt`
|
|
3592
|
+
10. Use `getEntitlements()` instead of `allEntitlements.data`
|
|
3593
|
+
11. Use `getRawEntitlements()` for un-aggregated API data
|
|
3594
|
+
|
|
3595
|
+
</Update>
|
|
3596
|
+
|
|
3597
|
+
<Update label="v2.0.0" description="February 27, 2026" tags={["Node SDK"]}>
|
|
3598
|
+
|
|
3599
|
+
### New Features
|
|
3600
|
+
|
|
3601
|
+
#### Entitlements Aggregation Engine
|
|
3602
|
+
|
|
3603
|
+
When a customer has multiple subscriptions, the API can return duplicate `featureId` entries. The SDK now automatically aggregates them into a single `Entitlement` object per feature:
|
|
3604
|
+
|
|
3605
|
+
- Numeric fields (`usageLimit`, `currentUsage`, `remaining`) are **summed** across all entries
|
|
3606
|
+
- `hasAccess` is `true` if **any** raw entry grants access
|
|
3607
|
+
- `hardLimit` is `true` if **any** entry sets it
|
|
3608
|
+
- All raw entries are preserved in the `.items[]` array
|
|
3609
|
+
|
|
3610
|
+
```typescript
|
|
3611
|
+
const entitlement = await client.entitlements.getEntitlement({
|
|
3612
|
+
customerId: "cust_123",
|
|
3613
|
+
featureId: "email-sends",
|
|
3614
|
+
});
|
|
3615
|
+
|
|
3616
|
+
// Aggregated values across all subscriptions
|
|
3617
|
+
console.log(entitlement.hasAccess); // true
|
|
3618
|
+
console.log(entitlement.usageLimit); // 1500 (e.g., 1000 from base plan + 500 from top-up)
|
|
3619
|
+
console.log(entitlement.currentUsage); // 200
|
|
3620
|
+
console.log(entitlement.remaining); // 1300
|
|
3621
|
+
|
|
3622
|
+
// Per-subscription details
|
|
3623
|
+
entitlement.items.forEach(item => {
|
|
3624
|
+
console.log(item.usageLimit, item.resetAt);
|
|
3625
|
+
});
|
|
3626
|
+
```
|
|
3627
|
+
|
|
3628
|
+
#### `Entitlement` Interface
|
|
3629
|
+
|
|
3630
|
+
New type representing an aggregated entitlement with an `items: EntitlementDetail[]` field containing the raw entries that were aggregated.
|
|
3631
|
+
|
|
3632
|
+
#### `getRawEntitlement({ customerId, featureId })`
|
|
3633
|
+
|
|
3634
|
+
Returns the raw API response for a specific feature (`CheckEntitlementsResponse` with `customerId` wrapper), without any aggregation:
|
|
3635
|
+
|
|
3636
|
+
```typescript
|
|
3637
|
+
const raw = await client.entitlements.getRawEntitlement({
|
|
3638
|
+
customerId: "cust_123",
|
|
3639
|
+
featureId: "email-sends",
|
|
3640
|
+
});
|
|
3641
|
+
// { customerId: "cust_123", entitlements: [/* raw entries for email-sends */] }
|
|
3642
|
+
```
|
|
3643
|
+
|
|
3644
|
+
#### `getRawEntitlements({ customerId })`
|
|
3645
|
+
|
|
3646
|
+
Returns the raw API response for all entitlements, without any aggregation:
|
|
3647
|
+
|
|
3648
|
+
```typescript
|
|
3649
|
+
const raw = await client.entitlements.getRawEntitlements({
|
|
3650
|
+
customerId: "cust_123",
|
|
3651
|
+
});
|
|
3652
|
+
// { customerId: "cust_123", entitlements: [/* all raw entries */] }
|
|
3653
|
+
```
|
|
3654
|
+
|
|
3655
|
+
#### `client.subscription` Deprecated Alias
|
|
3656
|
+
|
|
3657
|
+
A backward-compatible getter that maps `client.subscription` to `client.subscriptions`, so existing code continues to work during migration.
|
|
3658
|
+
|
|
3659
|
+
---
|
|
3660
|
+
|
|
3661
|
+
### Breaking Changes
|
|
3662
|
+
|
|
3663
|
+
#### `client.subscription` Renamed to `client.subscriptions`
|
|
3664
|
+
|
|
3665
|
+
The subscriptions module now uses the plural form for consistency with other modules (`client.customers`, `client.entitlements`, etc.):
|
|
3666
|
+
|
|
3667
|
+
```typescript
|
|
3668
|
+
// Before
|
|
3669
|
+
const sub = await client.subscription.get({ subscriptionId: "sub_123" });
|
|
3670
|
+
|
|
3671
|
+
// After
|
|
3672
|
+
const sub = await client.subscriptions.get({ subscriptionId: "sub_123" });
|
|
3673
|
+
```
|
|
3674
|
+
|
|
3675
|
+
The old `client.subscription` accessor still works as a deprecated alias.
|
|
3676
|
+
|
|
3677
|
+
#### `getEntitlement()` Returns `Entitlement | null`
|
|
3678
|
+
|
|
3679
|
+
Previously returned `CheckEntitlementsResponse` (the raw API shape with a `customerId` wrapper). Now returns a single aggregated `Entitlement` object with an `.items[]` array, or `null` if the feature is not found:
|
|
3680
|
+
|
|
3681
|
+
```typescript
|
|
3682
|
+
// Before
|
|
3683
|
+
const response = await client.entitlements.getEntitlement({
|
|
3684
|
+
customerId: "cust_123",
|
|
3685
|
+
featureId: "email-sends",
|
|
3686
|
+
});
|
|
3687
|
+
// { customerId: "cust_123", entitlements: [...] }
|
|
3688
|
+
|
|
3689
|
+
// After
|
|
3690
|
+
const entitlement = await client.entitlements.getEntitlement({
|
|
3691
|
+
customerId: "cust_123",
|
|
3692
|
+
featureId: "email-sends",
|
|
3693
|
+
});
|
|
3694
|
+
// { featureId: "email-sends", hasAccess: true, currentUsage: 200, ... }
|
|
3695
|
+
```
|
|
3696
|
+
|
|
3697
|
+
For the original raw API response, use `getRawEntitlement()`.
|
|
3698
|
+
|
|
3699
|
+
#### `getAllEntitlements()` Removed
|
|
3700
|
+
|
|
3701
|
+
Replaced by `getEntitlements()`, which returns `Record<string, Entitlement>` — a record keyed by `featureId` with aggregated values and an `.items[]` array:
|
|
3702
|
+
|
|
3703
|
+
```typescript
|
|
3704
|
+
// Before
|
|
3705
|
+
const response = await client.entitlements.getAllEntitlements({ customerId: "cust_123" });
|
|
3706
|
+
|
|
3707
|
+
// After
|
|
3708
|
+
const entitlements = await client.entitlements.getEntitlements({ customerId: "cust_123" });
|
|
3709
|
+
// { "email-sends": Entitlement, "api-calls": Entitlement, ... }
|
|
3710
|
+
```
|
|
3711
|
+
|
|
3712
|
+
For the original raw API response, use `getRawEntitlements()`.
|
|
3713
|
+
|
|
3714
|
+
#### `FeatureType` Changed: `"LIMIT"` → `"CUSTOMIZABLE"`
|
|
3715
|
+
|
|
3716
|
+
The `FeatureType` union no longer includes `"LIMIT"`. Update any code that matches on this value:
|
|
3717
|
+
|
|
3718
|
+
```typescript
|
|
3719
|
+
// Before
|
|
3720
|
+
if (entitlement.featureType === "LIMIT") { ... }
|
|
3721
|
+
|
|
3722
|
+
// After
|
|
3723
|
+
if (entitlement.featureType === "CUSTOMIZABLE") { ... }
|
|
3724
|
+
```
|
|
3725
|
+
|
|
3726
|
+
#### `resetAt` Removed from Aggregated `Entitlement`
|
|
3727
|
+
|
|
3728
|
+
Since `resetAt` can differ across subscriptions, it is only available on individual items:
|
|
3729
|
+
|
|
3730
|
+
```typescript
|
|
3731
|
+
// Before
|
|
3732
|
+
console.log(entitlement.resetAt);
|
|
3733
|
+
|
|
3734
|
+
// After
|
|
3735
|
+
entitlement.items.forEach(item => {
|
|
3736
|
+
console.log(item.resetAt); // per-subscription reset date
|
|
3737
|
+
});
|
|
3738
|
+
```
|
|
3739
|
+
|
|
3740
|
+
---
|
|
3741
|
+
|
|
3742
|
+
### Fixed
|
|
3743
|
+
|
|
3744
|
+
- Fixed Python-style `try/except` syntax in subscription update documentation — replaced with JavaScript `try...catch`.
|
|
3745
|
+
- Added missing `try/catch` error handling to subscription cancel documentation example.
|
|
3746
|
+
- Removed invalid JSON comments (`// Server-generated UUID`) from documentation response blocks.
|
|
3747
|
+
- Fixed trailing comma in checkout session JSON response example.
|
|
3748
|
+
- Fixed `"Node SDK Use"` typo → `"Node SDK User"` in create customer documentation.
|
|
3749
|
+
- Fixed `True` → `true`, `bool` → `boolean` in `hasAccess` documentation.
|
|
3750
|
+
- Replaced "Pydantic model" references with "TypeScript Interface" or "Object".
|
|
3751
|
+
- Replaced "Dictionary" with "Object" in parameter descriptions.
|
|
3752
|
+
- Fixed Python-style `ACCESS_TOKEN = "..."` → `const ACCESS_TOKEN = "...";` in setup example.
|
|
3753
|
+
|
|
3754
|
+
</Update>
|
|
3755
|
+
|
|
3756
|
+
<Update label="v2.0.0" description="February 27, 2026" tags={["Python SDK"]}>
|
|
3757
|
+
|
|
3758
|
+
### New Features
|
|
3759
|
+
|
|
3760
|
+
#### Entitlements Aggregation Engine
|
|
3761
|
+
|
|
3762
|
+
When a customer has multiple active subscriptions, the API can return duplicate `featureId` entries. The SDK now automatically aggregates them into a single `Entitlement` model while preserving the raw data.
|
|
3763
|
+
|
|
3764
|
+
```python
|
|
3765
|
+
entitlement = client.entitlements.get_entitlement("cust_123", "email-sends")
|
|
3766
|
+
|
|
3767
|
+
# Aggregated values across all subscriptions
|
|
3768
|
+
print(entitlement.hasAccess) # True
|
|
3769
|
+
print(entitlement.usageLimit) # 1500 (e.g., 1000 from base + 500 from top-up)
|
|
3770
|
+
print(entitlement.currentUsage) # 200
|
|
3771
|
+
print(entitlement.remaining) # 1300
|
|
3772
|
+
|
|
3773
|
+
# Per-subscription details
|
|
3774
|
+
for item in entitlement.items:
|
|
3775
|
+
print(item.usageLimit, item.resetAt)
|
|
3776
|
+
```
|
|
3777
|
+
|
|
3778
|
+
**Aggregation rules:**
|
|
3779
|
+
|
|
3780
|
+
| Field | Aggregation Strategy |
|
|
3781
|
+
|---|---|
|
|
3782
|
+
| `hasAccess` | `True` if **any** raw entry grants access |
|
|
3783
|
+
| `usageLimit` | **Summed** across all entries (for `METER` feature types) |
|
|
3784
|
+
| `currentUsage` | **Summed** across all entries (for `METER` feature types) |
|
|
3785
|
+
| `remaining` | Computed as `usageLimit - currentUsage` |
|
|
3786
|
+
| `hardLimit` | `True` if **any** entry has a hard limit |
|
|
3787
|
+
|
|
3788
|
+
> **Note:** `resetAt` is intentionally **not** aggregated at the top level because each subscription item can have a different reset date. Access individual reset dates via `entitlement.items[i].resetAt`.
|
|
3789
|
+
|
|
3790
|
+
#### New `Entitlement` Pydantic Model
|
|
3791
|
+
|
|
3792
|
+
A new model representing an aggregated entitlement:
|
|
3793
|
+
|
|
3794
|
+
- `featureId`, `featureType`, `hasAccess`, `hardLimit`, `usageLimit`, `currentUsage`, `remaining`
|
|
3795
|
+
- `items: List[EntitlementDetail]` — the raw entries that were aggregated into this model
|
|
3796
|
+
|
|
3797
|
+
#### `get_entitlements(customerId)` — All Entitlements as a Map
|
|
3798
|
+
|
|
3799
|
+
Returns a `Dict[str, Entitlement]` keyed by `featureId`. Each value is an aggregated model with an `.items` list containing the original raw entries.
|
|
3800
|
+
|
|
3801
|
+
```python
|
|
3802
|
+
entitlements = client.entitlements.get_entitlements("cust_123")
|
|
3803
|
+
|
|
3804
|
+
for feature_id, entitlement in entitlements.items():
|
|
3805
|
+
print(f"{feature_id}: hasAccess={entitlement.hasAccess}, remaining={entitlement.remaining}")
|
|
3806
|
+
```
|
|
3807
|
+
|
|
3808
|
+
#### `get_raw_entitlement(customerId, featureId)` — Raw API Response for a Feature
|
|
3809
|
+
|
|
3810
|
+
Returns the raw API response (`CheckEntitlementsResponse`) for a specific feature without any aggregation.
|
|
3811
|
+
|
|
3812
|
+
```python
|
|
3813
|
+
raw = client.entitlements.get_raw_entitlement("cust_123", "email-sends")
|
|
3814
|
+
```
|
|
3815
|
+
|
|
3816
|
+
#### `get_raw_entitlements(customerId)` — Full Raw API Response
|
|
3817
|
+
|
|
3818
|
+
Returns the raw API response for all entitlements without any aggregation.
|
|
3819
|
+
|
|
3820
|
+
```python
|
|
3821
|
+
raw = client.entitlements.get_raw_entitlements("cust_123")
|
|
3822
|
+
```
|
|
3823
|
+
|
|
3824
|
+
#### Enum Helpers for IDE Autocompletion
|
|
3825
|
+
|
|
3826
|
+
New `str`-based `Enum` classes:
|
|
3827
|
+
|
|
3828
|
+
- **`ChargePeriod`** — `ONE_TIME`, `MONTHLY`, `YEARLY`, `WEEKLY`, `DAILY`, `THREE_MONTHS`, `SIX_MONTHS`
|
|
3829
|
+
- **`CancellationType`** — `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, `SPECIFIC_DATE`
|
|
3830
|
+
|
|
3831
|
+
```python
|
|
3832
|
+
from kelviq_sdk import ChargePeriod, CancellationType
|
|
3833
|
+
|
|
3834
|
+
response = client.checkout.create_session(
|
|
3835
|
+
planIdentifier="pro-plan",
|
|
3836
|
+
chargePeriod=ChargePeriod.MONTHLY,
|
|
3837
|
+
successUrl="https://example.com/success"
|
|
3838
|
+
)
|
|
3839
|
+
```
|
|
3840
|
+
|
|
3841
|
+
Raw string values (e.g., `"MONTHLY"`) continue to work everywhere — fully backward-compatible.
|
|
3842
|
+
|
|
3843
|
+
---
|
|
3844
|
+
|
|
3845
|
+
### Changed
|
|
3846
|
+
|
|
3847
|
+
- **`get_entitlement(customerId, featureId)`** now returns `Optional[Entitlement]` (aggregated) instead of raw `CheckEntitlementsResponse`. Use `get_raw_entitlement()` for the original response.
|
|
3848
|
+
- **`get_all_entitlements` removed** — Use `get_entitlements()` instead.
|
|
3849
|
+
- **`resetAt` removed from top-level `Entitlement`** — Access individual reset dates via the `.items` list.
|
|
3850
|
+
|
|
3851
|
+
</Update>
|
|
3852
|
+
|
|
3853
|
+
<Update label="v1.1.0" description="February 27, 2026" tags={["Python SDK"]}>
|
|
3854
|
+
|
|
3855
|
+
### New Features
|
|
3856
|
+
|
|
3857
|
+
#### Entitlements Aggregation Engine
|
|
3858
|
+
|
|
3859
|
+
When a customer has multiple active subscriptions, the API can return duplicate `featureId` entries. The SDK now automatically aggregates them into a single `Entitlement` model while preserving the raw data.
|
|
3860
|
+
|
|
3861
|
+
```python
|
|
3862
|
+
entitlement = client.entitlements.get_entitlement("cust_123", "email-sends")
|
|
3863
|
+
|
|
3864
|
+
# Aggregated values across all subscriptions
|
|
3865
|
+
print(entitlement.has_access) # True
|
|
3866
|
+
print(entitlement.usage_limit) # 1500 (e.g., 1000 from base + 500 from top-up)
|
|
3867
|
+
print(entitlement.current_usage) # 200
|
|
3868
|
+
print(entitlement.remaining) # 1300
|
|
3869
|
+
|
|
3870
|
+
# Per-subscription details
|
|
3871
|
+
for item in entitlement.items:
|
|
3872
|
+
print(item.usage_limit, item.reset_at)
|
|
3873
|
+
```
|
|
3874
|
+
|
|
3875
|
+
**Aggregation rules:**
|
|
3876
|
+
|
|
3877
|
+
| Field | Aggregation Strategy |
|
|
3878
|
+
|---|---|
|
|
3879
|
+
| `hasAccess` | `True` if **any** raw entry grants access |
|
|
3880
|
+
| `usageLimit` | **Summed** across all entries (for `METER` feature types) |
|
|
3881
|
+
| `currentUsage` | **Summed** across all entries (for `METER` feature types) |
|
|
3882
|
+
| `remaining` | Computed as `usageLimit - currentUsage` |
|
|
3883
|
+
| `hardLimit` | `True` if **any** entry has a hard limit |
|
|
3884
|
+
|
|
3885
|
+
> **Note:** `resetAt` is intentionally **not** aggregated at the top level because each subscription item can have a different reset date. Access individual reset dates via `entitlement.items[i].resetAt`.
|
|
3886
|
+
|
|
3887
|
+
#### New `Entitlement` Pydantic Model
|
|
3888
|
+
|
|
3889
|
+
A new model representing an aggregated entitlement:
|
|
3890
|
+
|
|
3891
|
+
- `featureId`, `featureType`, `hasAccess`, `hardLimit`, `usageLimit`, `currentUsage`, `remaining`
|
|
3892
|
+
- `items: List[EntitlementDetail]` — the raw entries that were aggregated into this model
|
|
3893
|
+
|
|
3894
|
+
#### `get_entitlements(customerId)` — All Entitlements as a Map
|
|
3895
|
+
|
|
3896
|
+
Returns a `Dict[str, Entitlement]` keyed by `featureId`. Each value is an aggregated model with an `.items` list containing the original raw entries.
|
|
3897
|
+
|
|
3898
|
+
```python
|
|
3899
|
+
entitlements = client.entitlements.get_entitlements("cust_123")
|
|
3900
|
+
|
|
3901
|
+
for feature_id, entitlement in entitlements.items():
|
|
3902
|
+
print(f"{feature_id}: hasAccess={entitlement.has_access}, remaining={entitlement.remaining}")
|
|
3903
|
+
```
|
|
3904
|
+
|
|
3905
|
+
#### `get_raw_entitlement(customerId, featureId)` — Raw API Response for a Feature
|
|
3906
|
+
|
|
3907
|
+
Returns the raw API response (`CheckEntitlementsResponse`) for a specific feature without any aggregation. Includes the `customerId` wrapper.
|
|
3908
|
+
|
|
3909
|
+
```python
|
|
3910
|
+
raw = client.entitlements.get_raw_entitlement("cust_123", "email-sends")
|
|
3911
|
+
# CheckEntitlementsResponse with customerId wrapper
|
|
3912
|
+
```
|
|
3913
|
+
|
|
3914
|
+
#### `get_raw_entitlements(customerId)` — Full Raw API Response
|
|
3915
|
+
|
|
3916
|
+
Returns the raw API response for all entitlements without any aggregation.
|
|
3917
|
+
|
|
3918
|
+
```python
|
|
3919
|
+
raw = client.entitlements.get_raw_entitlements("cust_123")
|
|
3920
|
+
# CheckEntitlementsResponse with customerId wrapper and all raw entries
|
|
3921
|
+
```
|
|
3922
|
+
|
|
3923
|
+
#### Enum Helpers for IDE Autocompletion
|
|
3924
|
+
|
|
3925
|
+
New `str`-based `Enum` classes that improve developer experience with IDE autocompletion and prevent typos:
|
|
3926
|
+
|
|
3927
|
+
- **`ChargePeriod`** — `ONE_TIME`, `MONTHLY`, `YEARLY`, `WEEKLY`, `DAILY`, `THREE_MONTHS`, `SIX_MONTHS`
|
|
3928
|
+
- **`CancellationType`** — `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, `SPECIFIC_DATE`
|
|
3929
|
+
|
|
3930
|
+
```python
|
|
3931
|
+
from kelviq_sdk import ChargePeriod, CancellationType
|
|
3932
|
+
|
|
3933
|
+
# With enums — IDE autocompletion and typo prevention
|
|
3934
|
+
response = client.checkout.create_session(
|
|
3935
|
+
planIdentifier="pro-plan",
|
|
3936
|
+
chargePeriod=ChargePeriod.MONTHLY,
|
|
3937
|
+
successUrl="https://example.com/success"
|
|
3938
|
+
)
|
|
3939
|
+
|
|
3940
|
+
# Cancel with enum
|
|
3941
|
+
client.subscriptions.cancel(
|
|
3942
|
+
subscriptionId="sub_123",
|
|
3943
|
+
cancellationType=CancellationType.CURRENT_PERIOD_ENDS,
|
|
3944
|
+
)
|
|
3945
|
+
```
|
|
3946
|
+
|
|
3947
|
+
Raw string values (e.g., `"MONTHLY"`) continue to work everywhere — the enums are fully backward-compatible.
|
|
3948
|
+
|
|
3949
|
+
---
|
|
3950
|
+
|
|
3951
|
+
### Changed
|
|
3952
|
+
|
|
3953
|
+
- **`get_entitlement(customerId, featureId)`** now returns `Optional[Entitlement]` (aggregated) instead of raw `CheckEntitlementsResponse`. Use `get_raw_entitlement()` if you need the original response.
|
|
3954
|
+
- **`get_all_entitlements` removed** — Use `get_entitlements()` instead, which returns a `Dict[str, Entitlement]` keyed by `featureId`.
|
|
3955
|
+
- **`resetAt` removed from top-level `Entitlement`** — Access individual reset dates via the `.items` list.
|
|
3956
|
+
|
|
3957
|
+
---
|
|
3958
|
+
|
|
3959
|
+
### Fixed
|
|
3960
|
+
|
|
3961
|
+
- Removed invalid JavaScript-style comments (`// Server-generated UUID`) from JSON response blocks in documentation.
|
|
3962
|
+
- Fixed `//` comments to `#` comments in Python code snippets.
|
|
3963
|
+
- Fixed trailing comma in Checkout response JSON block.
|
|
3964
|
+
- Fixed typo: "newly created customer" → "**updated** customer" in `customers.update` return description.
|
|
3965
|
+
- Removed placeholder text from "Supported Functionalities" section.
|
|
3966
|
+
- Updated entitlements description to explain multi-subscription aggregation and the `items` attribute.
|
|
3967
|
+
|
|
3968
|
+
</Update>
|