@kelviq/mcp-server 1.0.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.
@@ -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
+ ![Kelviq release cover for June 26, 2026](/images/changelog/2026-06-26.png)
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
+ ![Kelviq release cover for June 19, 2026](/images/changelog/2026-06-19.png)
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
+ ![Kelviq release cover for June 12, 2026](/images/changelog/2026-06-12.png)
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
+ ![Kelviq release cover for June 5, 2026](/images/changelog/2026-06-05.png)
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
+ ![Kelviq release cover for May 29, 2026](/images/changelog/2026-05-29.png)
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
+ ![Kelviq release cover for May 22, 2026](/images/changelog/2026-05-22.png)
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>