@kelviq/mcp-server 0.4.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +34 -26
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +23 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +114 -34
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +102 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/server.js +10 -1
  62. package/dist/server.js.map +1 -1
  63. package/package.json +1 -1
@@ -4,23 +4,534 @@ slug: "changelog/api"
4
4
  section: "changelog"
5
5
  description: "Changelog for the Kelviq API"
6
6
  ---
7
- <Update label="v1.3.1" description="July 21, 2026">
7
+ <Update label="v1.7.9" description="September 15, 2026">
8
8
 
9
9
  ### New Features
10
10
 
11
- #### Activate Subscription Updates After Payment
11
+ #### Discounts API
12
12
 
13
- `POST /subscriptions/{subscriptionId}/update/` now accepts the optional `paymentBehavior` field. Set it to `activate_on_payment` to keep the customer's current subscription active while payment for the change is pending.
13
+ Discount codes can now be managed directly through the API, authenticated with your server API key:
14
+
15
+ - `GET /discount/` — list discounts
16
+ - `POST /discount/` — create a discount (Merchant of Record organizations only)
17
+ - `GET /discount/{id}/` — retrieve a discount
18
+ - `PATCH /discount/{id}/` — enable or disable a discount
19
+ - `DELETE /discount/{id}/` — archive a discount
20
+
21
+ ```json
22
+ {
23
+ "discountType": "PERCENTAGE",
24
+ "percentageOff": 20,
25
+ "name": "Summer Sale",
26
+ "code": "SUMMER20",
27
+ "duration": "ONCE"
28
+ }
29
+ ```
30
+
31
+ 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`.
32
+
33
+ #### Manage webhook endpoints via API
34
+
35
+ `WebhookEndpoint` resources — previously dashboard-only — are now fully manageable through the API:
36
+
37
+ - `GET /webhook/endpoints/` — list webhook endpoints
38
+ - `POST /webhook/endpoints/` — create a webhook endpoint
39
+ - `GET /webhook/endpoints/{id}/` — retrieve a webhook endpoint
40
+ - `PATCH /webhook/endpoints/{id}/` — update the URL, subscribed events, or enabled state
41
+ - `DELETE /webhook/endpoints/{id}/` — delete a webhook endpoint
42
+
43
+ ```json
44
+ {
45
+ "url": "https://example.com/webhooks/kelviq",
46
+ "events": ["invoice.paid", "subscription.cancelled"],
47
+ "enabled": true
48
+ }
49
+ ```
50
+
51
+ The signing secret used to verify the `Kelviq-Signature` header is generated automatically and returned in the create response.
52
+
53
+ </Update>
54
+
55
+ <Update label="v1.7.8" description="September 10, 2026">
56
+
57
+ ### New Features
58
+
59
+ #### Limit checkout to selected billing periods
60
+
61
+ `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.
62
+
63
+ ```json
64
+ {
65
+ "planIdentifier": "premium-plan",
66
+ "chargePeriod": "MONTHLY",
67
+ "billingPeriodsEnabled": "MONTHLY,YEARLY",
68
+ "successUrl": "https://example.com/checkout/success"
69
+ }
70
+ ```
71
+
72
+ `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.
73
+
74
+ #### Prefill the checkout email address
75
+
76
+ `POST /checkout/` now accepts `email` to prefill the checkout page. Combine it with `lockEmail: true` when the customer must not edit the address.
77
+
78
+ ```json
79
+ {
80
+ "planIdentifier": "premium-plan",
81
+ "chargePeriod": "MONTHLY",
82
+ "email": "customer@example.com",
83
+ "lockEmail": true,
84
+ "successUrl": "https://example.com/checkout/success"
85
+ }
86
+ ```
87
+
88
+ Static checkout links can prefill the same value with the `email` query parameter.
89
+
90
+ </Update>
91
+
92
+ <Update label="v1.7.7" description="September 7, 2026">
93
+
94
+ ### New Features
95
+
96
+ #### Set a custom trial period at checkout
97
+
98
+ `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.
99
+
100
+ ```json
101
+ {
102
+ "planIdentifier": "premium-plan",
103
+ "chargePeriod": "MONTHLY",
104
+ "trialPeriod": 14,
105
+ "successUrl": "https://example.com/checkout/success"
106
+ }
107
+ ```
108
+
109
+ ### Changes
110
+
111
+ #### Success URL is required
112
+
113
+ `successUrl` is mandatory when calling `POST /checkout/`. Requests that omit it are rejected with a `400` response.
114
+
115
+ </Update>
116
+
117
+ <Update label="v1.7.6" description="August 20, 2026">
118
+
119
+ ### New Features
120
+
121
+ #### Organization-level proration defaults
122
+
123
+ `GET /organizations/settings/` and `PATCH /organizations/settings/` now expose two settings for controlling how subscription changes are prorated:
124
+
125
+ | Setting | Default | Used when |
126
+ | --- | --- | --- |
127
+ | `updateSubscriptionProrationBehavior` | `IMMEDIATE_CHARGE` | A subscription is upgraded or downgraded without a `prorationBehavior` in the update request. |
128
+ | `migrateSubscriptionProrationBehavior` | `PRORATE_NEXT_INVOICE` | A subscription is migrated to the latest version of its plan. |
129
+
130
+ Both settings accept `IMMEDIATE_CHARGE`, `PRORATE_NEXT_INVOICE`, or `NO_PRORATION`.
131
+
132
+ ```json
133
+ {
134
+ "updateSubscriptionProrationBehavior": "IMMEDIATE_CHARGE",
135
+ "migrateSubscriptionProrationBehavior": "PRORATE_NEXT_INVOICE"
136
+ }
137
+ ```
138
+
139
+ #### Organization checkout customization
140
+
141
+ 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.
142
+
143
+ The hosted checkout session response now includes these settings so the organization's branding can be applied consistently across checkout sessions.
144
+
145
+ #### Migrate individual subscriptions
146
+
147
+ `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`:
148
+
149
+ ```json
150
+ {
151
+ "updateFeatures": true,
152
+ "updatePricing": true
153
+ }
154
+ ```
155
+
156
+ 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.
157
+
158
+ ### Changes
159
+
160
+ #### Identify custom-priced subscriptions
161
+
162
+ `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.
163
+
164
+ ```json
165
+ {
166
+ "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
167
+ "isCustomPricing": true
168
+ }
169
+ ```
170
+
171
+ </Update>
172
+
173
+ <Update label="v1.7.5" description="August 14, 2026">
174
+
175
+ ### New Features
176
+
177
+ #### Control how subscription updates are billed
178
+
179
+ `POST /subscriptions/{subscriptionId}/update/` and its `/preview/` counterpart now accept `prorationBehavior`, which controls when the customer is billed for a mid-period change:
180
+
181
+ | Value | Effect |
182
+ | --- | --- |
183
+ | `IMMEDIATE_CHARGE` | Prorates and invoices the difference right now. |
184
+ | `PRORATE_NEXT_INVOICE` | Prorates now, but bills it on the next invoice. |
185
+ | `NO_PRORATION` | Changes the plan immediately without crediting or charging for the partial period; the next invoice bills the full new price. |
186
+
187
+ If omitted, your organization's existing default is used, so existing integrations are unaffected.
14
188
 
15
189
  ```json
16
190
  {
17
191
  "planIdentifier": "premium-plan",
18
192
  "chargePeriod": "MONTHLY",
19
- "paymentBehavior": "activate_on_payment"
193
+ "prorationBehavior": "PRORATE_NEXT_INVOICE"
20
194
  }
21
195
  ```
22
196
 
23
- The new plan, billing period, and feature changes are applied only after payment succeeds. If the pending update expires before payment is completed, the current subscription remains unchanged. Omitting `paymentBehavior` preserves the existing immediate-update behavior.
197
+ Invalid values are now rejected with a clear `400` naming the accepted values, instead of a generic error.
198
+
199
+ 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.
200
+
201
+ ### Improvements
202
+
203
+ `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.
204
+
205
+ ### Deprecations
206
+
207
+ 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.
208
+
209
+ </Update>
210
+
211
+ <Update label="v1.7.4" description="August 12, 2026">
212
+
213
+ ### New Features
214
+
215
+ #### Preview subscription updates
216
+
217
+ 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.
218
+
219
+ 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.
220
+
221
+ ```json
222
+ {
223
+ "currency": "USD",
224
+ "recurringAmount": 50,
225
+ "recurringAmountUnits": 5000,
226
+ "amountChargedImmediately": 39.5,
227
+ "amountChargedImmediatelyUnits": 3950,
228
+ "nextInvoice": {
229
+ "amountDue": 39.5,
230
+ "amountDueUnits": 3950,
231
+ "nextPaymentAttempt": "2026-09-01T00:00:00Z",
232
+ "lineItems": [
233
+ {
234
+ "description": "Remaining time on Enterprise after 12 Aug 2026",
235
+ "amount": 39.5,
236
+ "amountUnits": 3950
237
+ }
238
+ ]
239
+ }
240
+ }
241
+ ```
242
+
243
+ #### Custom amounts for one-time charges
244
+
245
+ `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`.
246
+
247
+ ```json
248
+ {
249
+ "planIdentifier": "lifetime-access",
250
+ "chargePeriod": "ONE_TIME",
251
+ "customerId": "cust_789",
252
+ "currencyCode": "USD",
253
+ "customAmount": 49.99,
254
+ "taxBehavior": "INCLUSIVE"
255
+ }
256
+ ```
257
+
258
+ </Update>
259
+
260
+ <Update label="v1.7.3" description="August 10, 2026">
261
+
262
+ ### New Features
263
+
264
+ #### Trial ending webhook
265
+
266
+ 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`.
267
+
268
+ </Update>
269
+
270
+ <Update label="v1.7.2" description="August 10, 2026">
271
+
272
+ ### New Features
273
+
274
+ #### Invoices API
275
+
276
+ You can now list and retrieve invoices directly, rather than only receiving them through webhooks:
277
+
278
+ - `GET /invoices/` — a paginated list of invoices for your organization, filterable by `subscription_id` and `customer_id`.
279
+ - `GET /invoices/{invoiceId}/` — a single invoice by its Kelviq invoice ID.
280
+
281
+ The invoice object also has three new fields, matching what's already sent in invoice webhooks:
282
+
283
+ - `attemptCount` — number of payment attempts made against the invoice.
284
+ - `nextPaymentAttempt` — when Stripe will next retry collection, if a retry is scheduled.
285
+ - `failureDetails` — `code`, `message`, and `paymentMethodType` for the most recent failed payment attempt. `null` once the invoice is paid.
286
+
287
+ #### Filter subscriptions by modification date
288
+
289
+ `GET /subscriptions/` now accepts `modified_on_after` / `modified_on_before` query parameters, for filtering by when the subscription was last modified.
290
+
291
+ ```
292
+ GET /subscriptions/?modified_on_after=2026-08-01T00:00:00Z
293
+ ```
294
+
295
+ #### Subscription timestamps
296
+
297
+ `GET /subscriptions/` and `GET /subscriptions/{subscriptionId}/` now return `createdOn` and `modifiedOn` on the subscription object.
298
+
299
+ </Update>
300
+
301
+ <Update label="v1.7.1" description="August 5, 2026">
302
+
303
+ ### New Features
304
+
305
+ #### Payment links in invoice webhooks
306
+
307
+ 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.
308
+
309
+ `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.
310
+
311
+ Example:
312
+
313
+ ```json
314
+ {
315
+ "paymentLink": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz"
316
+ }
317
+ ```
318
+
319
+ ### Changes
320
+
321
+ #### Portal sessions require a customer email
322
+
323
+ `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.
324
+
325
+ </Update>
326
+
327
+ <Update label="v1.7.0" description="August 1, 2026">
328
+
329
+ ### New Features
330
+
331
+ #### Subscription cancellation details
332
+
333
+ `GET /subscriptions/` and `GET /subscriptions/{subscriptionId}/` now return cancellation metadata:
334
+
335
+ - `canceledAt` — when the cancellation was recorded.
336
+ - `cancellationReason` — whether it was initiated by the customer, merchant, or provider.
337
+ - `cancellationFeedback` — structured feedback such as `TOO_EXPENSIVE`, `MISSING_FEATURES`, or `UNUSED`.
338
+ - `cancellationComment` — an optional free-form comment.
339
+
340
+ `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.
341
+
342
+ #### Failed invoice webhook
343
+
344
+ 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`.
345
+
346
+ #### Refund webhook context
347
+
348
+ The `refund.created` and `refund.updated` webhook objects now include:
349
+
350
+ - `customer` — the associated customer's ID, name, email, customer identifier, and billing address.
351
+ - `subscription_id` — the associated subscription ID, or `null` for an order without a subscription.
352
+
353
+ #### Refunded order total
354
+
355
+ 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.
356
+
357
+ </Update>
358
+
359
+ <Update label="v1.6.3" description="July 29, 2026">
360
+
361
+ ### Fixes
362
+
363
+ #### `subscription.updated` now fires when a cancellation is scheduled for period-end
364
+
365
+ 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.
366
+
367
+ </Update>
368
+
369
+ <Update label="v1.6.2" description="July 29, 2026">
370
+
371
+ ### New Features
372
+
373
+ #### Checkout sessions and checkout session events
374
+
375
+ Three endpoints are now part of the public API:
376
+
377
+ - `GET /checkout/sessions/` — paginated list of checkout sessions for the authenticated organization.
378
+ - `GET /checkout/sessions/{session_id}/` — a single checkout session, including the order, subscription, and payment method it produced (if any).
379
+ - `GET /checkout/sessions/{session_id}/events/` — the session's timeline events (session created, customer details updated, payment attempted, payment completed, etc.).
380
+
381
+ </Update>
382
+
383
+ <Update label="v1.6.1" description="July 29, 2026">
384
+
385
+ ### New Features
386
+
387
+ #### Orders, order events, and webhook delivery logs
388
+
389
+ Four endpoints are now part of the public API:
390
+
391
+ - `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.
392
+ - `GET /orders/{id}/` — a single order.
393
+ - `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.
394
+ - `GET /webhook/logs/` — one row per webhook delivery attempt, including retries.
395
+
396
+ `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.
397
+
398
+ ```
399
+ GET /webhook/logs/?start_date=2026-07-20&end_date=2026-07-25
400
+ ```
401
+
402
+ ```
403
+ GET /orders/?billing_type=SUBSCRIPTION&is_renewal=false
404
+ ```
405
+
406
+ </Update>
407
+
408
+ <Update label="v1.6.0" description="July 29, 2026">
409
+
410
+ ### New Features
411
+
412
+ #### Filter subscriptions by status
413
+
414
+ `GET /subscriptions/` now accepts a `status` query parameter. Pass a comma-separated list to match any of several statuses, e.g. `?status=active,trialing`.
415
+
416
+ ```
417
+ GET /subscriptions/?status=active,trialing
418
+ ```
419
+
420
+ This changes the shape of the response compared to the default (no `status`) call:
421
+
422
+ - **Without `status`**: exactly one row per subscription — its most recent state, with expired (`end_date` in the past) and superseded records excluded.
423
+ - **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.
424
+
425
+ Use `status` for point-in-time queries ("show me everything currently `active`"); omit it for the current, deduplicated view of each subscription.
426
+
427
+ ### Fixes
428
+
429
+ #### HTTPS pagination links
430
+
431
+ 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.
432
+
433
+ </Update>
434
+
435
+ <Update label="v1.5.0" description="July 28, 2026">
436
+
437
+ ### Changes
438
+
439
+ #### Itemized Merchant of Record fees
440
+
441
+ Transaction responses from `GET /transaction/` now include `morFeeBreakdown`, an array that itemizes the Merchant of Record fee charged for the transaction.
442
+
443
+ 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.
444
+
445
+ ```json
446
+ {
447
+ "morFee": 4,
448
+ "morFeeBreakdown": [
449
+ {
450
+ "name": "fixed_fee",
451
+ "percentage": null,
452
+ "valueUnits": 40,
453
+ "currency": "USD"
454
+ },
455
+ {
456
+ "name": "base_fee",
457
+ "percentage": "2.9",
458
+ "valueUnits": 290,
459
+ "currency": "USD"
460
+ },
461
+ {
462
+ "name": "subscription_fee",
463
+ "percentage": "0.7",
464
+ "valueUnits": 70,
465
+ "currency": "USD"
466
+ }
467
+ ]
468
+ }
469
+ ```
470
+
471
+ 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.
472
+
473
+ </Update>
474
+
475
+ <Update label="v1.4.0" description="July 17, 2026">
476
+
477
+ ### New Features
478
+
479
+ #### 28-day subscription billing
480
+
481
+ 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.
482
+
483
+ 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.
484
+
485
+ ```json
486
+ {
487
+ "planIdentifier": "four-week-pro",
488
+ "chargePeriod": "TWENTY_EIGHT_DAYS",
489
+ "customerId": "customer_123",
490
+ "successUrl": "https://app.example.com/billing/success"
491
+ }
492
+ ```
493
+
494
+ Metered features that follow the same cadence can use `EVERY_28_DAYS` as their usage reset period.
495
+
496
+ 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.
497
+
498
+ #### Subscription end dates in webhook payloads
499
+
500
+ 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.
501
+
502
+ ```json
503
+ {
504
+ "type": "subscription.cancelled",
505
+ "data": {
506
+ "object": {
507
+ "id": "sub_123",
508
+ "end_date": "2026-08-17"
509
+ }
510
+ }
511
+ }
512
+ ```
513
+
514
+ Merchants can use this value to schedule access removal, customer notifications, and account cleanup without making a separate request for the latest subscription.
515
+
516
+ ### Fixes
517
+
518
+ #### Reliable `invoice.paid` webhook delivery
519
+
520
+ 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.
521
+
522
+ 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.
523
+
524
+ </Update>
525
+
526
+ <Update label="v1.3.1" description="July 17, 2026">
527
+
528
+ ### Changes
529
+
530
+ #### Multiple customers can use the same email
531
+
532
+ More than one customer record can now use the same email address. This removes the previous one-customer-per-email restriction.
533
+
534
+ 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.
24
535
 
25
536
  </Update>
26
537