@kelviq/mcp-server 0.4.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +43 -27
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/README.md +16 -0
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/changelog.md +3968 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +138 -35
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +98 -56
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +199 -0
- package/dist/schemas/kelviq.js +173 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +11 -1
- package/dist/server.js.map +1 -1
- package/dist/tools/discounts.d.ts +3 -0
- package/dist/tools/discounts.js +74 -0
- package/dist/tools/discounts.js.map +1 -0
- package/dist/tools/index.js +4 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/webhooks.d.ts +10 -0
- package/dist/tools/webhooks.js +114 -0
- package/dist/tools/webhooks.js.map +1 -0
- package/package.json +1 -1
|
@@ -4,6 +4,168 @@ slug: "changelog/app"
|
|
|
4
4
|
section: "changelog"
|
|
5
5
|
description: "Changelog for the Kelviq Dashboard"
|
|
6
6
|
---
|
|
7
|
+
<Update label="v1.17" description="August 21, 2026">
|
|
8
|
+
|
|
9
|
+
## Find transactions faster
|
|
10
|
+
|
|
11
|
+
Search on the **Payouts → Transactions** page now works properly, and filtering is more precise:
|
|
12
|
+
|
|
13
|
+
* A status filter narrows the list to successful, failed, or pending transactions.
|
|
14
|
+
* The search field matches payment method types. Search for `upi`, `card`, `link`, `amazon_pay`, or `sepa_debit` to see payments made through that method.
|
|
15
|
+
|
|
16
|
+
## Migrate subscriptions to the latest plan version
|
|
17
|
+
|
|
18
|
+
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.
|
|
19
|
+
|
|
20
|
+
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.
|
|
21
|
+
|
|
22
|
+
</Update>
|
|
23
|
+
|
|
24
|
+
<Update label="v1.16" description="August 7, 2026">
|
|
25
|
+
|
|
26
|
+
## Clearer subscription cancellation dates
|
|
27
|
+
|
|
28
|
+
Two fixes for cancelled subscriptions:
|
|
29
|
+
|
|
30
|
+
* The customer details page now shows when a subscription was cancelled, alongside its status.
|
|
31
|
+
* Cancelling a subscription from the dashboard now selects the correct cancellation date.
|
|
32
|
+
|
|
33
|
+
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/api) entry for v1.7.0.
|
|
34
|
+
|
|
35
|
+
</Update>
|
|
36
|
+
|
|
37
|
+
<Update label="v1.15" description="July 31, 2026">
|
|
38
|
+
|
|
39
|
+
## Kelviq now covers your payout fees
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
See [Fees](/getstarted/fees) for what a transaction costs and [Payouts](/payouts/overview) for how balances reach your bank.
|
|
44
|
+
|
|
45
|
+
## More billing periods
|
|
46
|
+
|
|
47
|
+
Plans now support a six-month billing period alongside monthly, quarterly, and yearly.
|
|
48
|
+
|
|
49
|
+
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.
|
|
50
|
+
|
|
51
|
+
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.
|
|
52
|
+
|
|
53
|
+
## Trials now default to 7 days
|
|
54
|
+
|
|
55
|
+
New free trials default to 7 days instead of 30. You can still set any duration from 1 to 365 days.
|
|
56
|
+
|
|
57
|
+
</Update>
|
|
58
|
+
|
|
59
|
+
<Update label="v1.14" description="July 24, 2026">
|
|
60
|
+
|
|
61
|
+
## Meet the Kelviq CLI (beta)
|
|
62
|
+
|
|
63
|
+
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.
|
|
64
|
+
|
|
65
|
+
The loop works in both directions:
|
|
66
|
+
|
|
67
|
+
* `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.
|
|
68
|
+
* `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.
|
|
69
|
+
* `kelviq promote` moves your whole sandbox catalog to production with the same preview and gates.
|
|
70
|
+
|
|
71
|
+
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.
|
|
72
|
+
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
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).
|
|
76
|
+
|
|
77
|
+
## A bigger, safer MCP server
|
|
78
|
+
|
|
79
|
+
Two releases of `@kelviq/mcp-server` shipped this week for teams driving Kelviq from Claude, Cursor, or any other MCP client.
|
|
80
|
+
|
|
81
|
+
**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.
|
|
82
|
+
|
|
83
|
+
**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.
|
|
84
|
+
|
|
85
|
+
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`.
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
</Update>
|
|
90
|
+
|
|
91
|
+
<Update label="v1.13" description="July 17, 2026">
|
|
92
|
+
|
|
93
|
+
## Safer discount creation
|
|
94
|
+
|
|
95
|
+
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.
|
|
96
|
+
|
|
97
|
+
Discount validation is also more reliable:
|
|
98
|
+
|
|
99
|
+
* Kelviq shows an error when a fixed-amount discount's currency does not match the selected price.
|
|
100
|
+
* Product-restricted discounts now use stricter product-selection validation during creation.
|
|
101
|
+
* 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.
|
|
102
|
+
* Fixed a bug that moved the cursor to the end of a discount field while typing.
|
|
103
|
+
|
|
104
|
+
## Trials now follow the selected billing model
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
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.
|
|
109
|
+
|
|
110
|
+
## Resend webhook deliveries from the dashboard
|
|
111
|
+
|
|
112
|
+
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.
|
|
113
|
+
|
|
114
|
+
The new attempt appears in the delivery logs, where you can inspect its status and response without waiting for another event.
|
|
115
|
+
|
|
116
|
+
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.
|
|
117
|
+
|
|
118
|
+
## Faster feature selection
|
|
119
|
+
|
|
120
|
+
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.
|
|
121
|
+
|
|
122
|
+
## Customer portal fixes
|
|
123
|
+
|
|
124
|
+
We fixed two customer portal edge cases:
|
|
125
|
+
|
|
126
|
+
* Login code input is normalized to uppercase as the customer types.
|
|
127
|
+
* The cancel action remains available for an active subscription when an associated order has been refunded.
|
|
128
|
+
|
|
129
|
+
</Update>
|
|
130
|
+
|
|
131
|
+
<Update label="v1.12" description="July 10, 2026">
|
|
132
|
+
|
|
133
|
+
## Customer deliverables in one place
|
|
134
|
+
|
|
135
|
+
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.
|
|
136
|
+
|
|
137
|
+
This makes common support requests faster, including:
|
|
138
|
+
|
|
139
|
+
* Finding a purchased download
|
|
140
|
+
* Opening a private resource link
|
|
141
|
+
* Reviewing an issued license key
|
|
142
|
+
* Managing a customer's license access
|
|
143
|
+
|
|
144
|
+
## Better feature and usage configuration
|
|
145
|
+
|
|
146
|
+
We improved the feature-management experience for metered and configurable entitlements:
|
|
147
|
+
|
|
148
|
+
* Numeric values now use number inputs where appropriate.
|
|
149
|
+
* Credit rollover appears before usage alerts, matching the order in which these settings are configured.
|
|
150
|
+
* Feature names can be edited from the feature row's action menu.
|
|
151
|
+
* Regional prices now carry over the base price's usage reset, usage alert, and credit rollover settings.
|
|
152
|
+
|
|
153
|
+
These changes reduce repetitive setup and keep entitlement behavior consistent across base and regional prices.
|
|
154
|
+
|
|
155
|
+
## Business details are easier to find
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
159
|
+
## Cleaner catalog, settings, and sandbox navigation
|
|
160
|
+
|
|
161
|
+
We simplified several dashboard workflows:
|
|
162
|
+
|
|
163
|
+
* Product identifiers are no longer shown or requested in the product interface. Kelviq uses the product's internal UUID.
|
|
164
|
+
* The sandbox no longer shows a **Start selling** action, because live selling is completed from the production environment.
|
|
165
|
+
* Settings navigation has clearer visual separation between groups.
|
|
166
|
+
|
|
167
|
+
</Update>
|
|
168
|
+
|
|
7
169
|
<Update label="v1.11" description="June 26, 2026">
|
|
8
170
|
|
|
9
171
|

|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "CLI"
|
|
3
|
+
slug: "changelog/cli"
|
|
4
|
+
section: "changelog"
|
|
5
|
+
description: "Changelog for @kelviq/cli"
|
|
6
|
+
---
|
|
7
|
+
<Update label="v0.3.0" description="September 15, 2026">
|
|
8
|
+
|
|
9
|
+
### Breaking Changes
|
|
10
|
+
|
|
11
|
+
#### `KELVIQ_SERVER_API_KEY` follows `KELVIQ_ENV`
|
|
12
|
+
|
|
13
|
+
`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.
|
|
14
|
+
|
|
15
|
+
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`.
|
|
16
|
+
|
|
17
|
+
### New Features
|
|
18
|
+
|
|
19
|
+
#### Environment-named keys
|
|
20
|
+
|
|
21
|
+
`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`.
|
|
22
|
+
|
|
23
|
+
### Improvements
|
|
24
|
+
|
|
25
|
+
- `kelviq env` shows which environment `KELVIQ_ENV` points your unprefixed variables at.
|
|
26
|
+
- 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.
|
|
27
|
+
- An invalid `KELVIQ_ENV` value stops the command instead of guessing.
|
|
28
|
+
|
|
29
|
+
### Fixes
|
|
30
|
+
|
|
31
|
+
- `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'`.
|
|
32
|
+
|
|
33
|
+
</Update>
|
|
@@ -4,6 +4,29 @@ slug: "changelog/mcp-server"
|
|
|
4
4
|
section: "changelog"
|
|
5
5
|
description: "Changelog for @kelviq/mcp-server"
|
|
6
6
|
---
|
|
7
|
+
<Update label="v1.0.0" description="September 14, 2026">
|
|
8
|
+
|
|
9
|
+
### Breaking Changes
|
|
10
|
+
|
|
11
|
+
#### Sandbox is now the default environment
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
### Improvements
|
|
18
|
+
|
|
19
|
+
- The startup log shows which environment the server is using, and warns when `KELVIQ_ENV` isn't set.
|
|
20
|
+
- The server tells the connected AI client which environment its tools act on.
|
|
21
|
+
- 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.
|
|
22
|
+
- Setup examples now run `npx -y @kelviq/mcp-server@latest`, so clients pick up new releases instead of a cached copy.
|
|
23
|
+
|
|
24
|
+
### Fixes
|
|
25
|
+
|
|
26
|
+
- 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.
|
|
27
|
+
|
|
28
|
+
</Update>
|
|
29
|
+
|
|
7
30
|
<Update label="v0.4.0" description="July 24, 2026">
|
|
8
31
|
|
|
9
32
|
### New Features
|
|
@@ -4,6 +4,130 @@ slug: "changelog/node-sdk"
|
|
|
4
4
|
section: "changelog"
|
|
5
5
|
description: "Changelog for @kelviq/node-sdk"
|
|
6
6
|
---
|
|
7
|
+
<Update label="v2.8.0" description="September 9, 2026">
|
|
8
|
+
|
|
9
|
+
### New Features
|
|
10
|
+
|
|
11
|
+
#### Refunds
|
|
12
|
+
|
|
13
|
+
A new `client.refunds` module lets you list, create, and retrieve refunds.
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
const refund = await client.refunds.create({
|
|
17
|
+
orderId: "ORD-20260715123000-A1B2C",
|
|
18
|
+
amountUnits: 2500,
|
|
19
|
+
reason: "REQUESTED_BY_CUSTOMER",
|
|
20
|
+
internalNote: "Customer requested a partial refund.",
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
const page = await client.refunds.list({ status: "SUCCEEDED", page: 1, pageSize: 10 });
|
|
24
|
+
|
|
25
|
+
const retrieved = await client.refunds.retrieve({ refundId: refund.id });
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`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.
|
|
29
|
+
|
|
30
|
+
#### Payment Methods
|
|
31
|
+
|
|
32
|
+
A new `client.paymentMethods` module lists saved payment methods, optionally filtered by `customerId` or `customerEmail`.
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
const methods = await client.paymentMethods.list({ customerId: "cust_789" });
|
|
36
|
+
console.log(methods.results[0].methodData.brand, methods.results[0].methodData.last4);
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Only payment methods with status `succeeded` are returned.
|
|
40
|
+
|
|
41
|
+
#### Transactions
|
|
42
|
+
|
|
43
|
+
A new `client.transactions` module lists financial transactions, including the itemized Merchant of Record fee breakdown when applicable.
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
const transactions = await client.transactions.list({ status: "success", startDate: "2026-07-01" });
|
|
47
|
+
console.log(transactions.results[0].amountTotal, transactions.results[0].morFeeBreakdown);
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`client.transactions.list()` supports `search`, `status`, `startDate`, `endDate`, `page`, and `pageSize` filters.
|
|
51
|
+
|
|
52
|
+
</Update>
|
|
53
|
+
|
|
54
|
+
<Update label="v2.7.4" description="September 8, 2026">
|
|
55
|
+
|
|
56
|
+
### New Features
|
|
57
|
+
|
|
58
|
+
#### Control How Subscription Updates Are Billed
|
|
59
|
+
|
|
60
|
+
`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.
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
import { CHARGE_PERIOD_CHOICES, PRORATION_BEHAVIORS } from "@kelviq/node-sdk";
|
|
64
|
+
|
|
65
|
+
const subscription = await client.subscriptions.update({
|
|
66
|
+
subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
67
|
+
planIdentifier: "premium-plan",
|
|
68
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
69
|
+
prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
|
|
70
|
+
});
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The SDK serializes the option as `proration_behavior`. Omit it to use your organization's default.
|
|
74
|
+
|
|
75
|
+
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.
|
|
76
|
+
|
|
77
|
+
#### Preview Subscription Updates
|
|
78
|
+
|
|
79
|
+
`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.
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
const preview = await client.subscriptions.previewUpdate({
|
|
83
|
+
subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
84
|
+
planIdentifier: "premium-plan",
|
|
85
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.YEARLY,
|
|
86
|
+
prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
|
|
87
|
+
features: [{ identifier: "seats", quantity: 10 }],
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
console.log(preview.recurringAmount, preview.amountChargedImmediately);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The response includes typed major- and minor-unit amounts, the next payment attempt, and preview invoice line items.
|
|
94
|
+
|
|
95
|
+
#### Set a Custom Trial Period at Checkout
|
|
96
|
+
|
|
97
|
+
`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.
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
const session = await client.checkout.createSession({
|
|
101
|
+
planIdentifier: "premium-plan",
|
|
102
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
103
|
+
successUrl: "https://example.com/checkout/success",
|
|
104
|
+
trialPeriod: 14,
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
#### Use a Custom Amount for One-Time Charges
|
|
109
|
+
|
|
110
|
+
`client.charges.create()` now accepts `customAmount` and `taxBehavior`. `customAmount` must be greater than zero and requires `currencyCode`; `taxBehavior` accepts `INCLUSIVE` or `EXCLUSIVE`.
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
const charge = await client.charges.create({
|
|
114
|
+
planIdentifier: "lifetime-access",
|
|
115
|
+
chargePeriod: "ONE_TIME",
|
|
116
|
+
customerId: "cust_789",
|
|
117
|
+
currencyCode: "USD",
|
|
118
|
+
customAmount: 49.99,
|
|
119
|
+
taxBehavior: "INCLUSIVE",
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Deprecations
|
|
124
|
+
|
|
125
|
+
`probationBehaviour` and `PROBATION_BEHAVIOURS` are deprecated in favour of `prorationBehavior` and `PRORATION_BEHAVIORS` (`probation` was a typo for `proration`). The old field still works.
|
|
126
|
+
|
|
127
|
+
`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.
|
|
128
|
+
|
|
129
|
+
</Update>
|
|
130
|
+
|
|
7
131
|
<Update label="v2.7.3" description="July 21, 2026">
|
|
8
132
|
|
|
9
133
|
### New Features
|
|
@@ -4,6 +4,141 @@ slug: "changelog/python-sdk"
|
|
|
4
4
|
section: "changelog"
|
|
5
5
|
description: "Changelog for kelviq-sdk (Python)"
|
|
6
6
|
---
|
|
7
|
+
<Update label="v2.8.0" description="September 9, 2026">
|
|
8
|
+
|
|
9
|
+
### New Features
|
|
10
|
+
|
|
11
|
+
#### Refunds
|
|
12
|
+
|
|
13
|
+
The synchronous and asynchronous clients now provide a `refunds` module for listing, creating, and retrieving refunds.
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
refund = client.refunds.create(
|
|
17
|
+
orderId="ORD-20260715123000-A1B2C",
|
|
18
|
+
amountUnits=2500,
|
|
19
|
+
reason="REQUESTED_BY_CUSTOMER",
|
|
20
|
+
internalNote="Customer requested a partial refund.",
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
page = client.refunds.list(status="SUCCEEDED", page=1, page_size=10)
|
|
24
|
+
|
|
25
|
+
retrieved = client.refunds.retrieve(refund.id)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**Async variant:**
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
refund = await async_client.refunds.create(
|
|
32
|
+
orderId="ORD-20260715123000-A1B2C",
|
|
33
|
+
amountUnits=2500,
|
|
34
|
+
)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`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.
|
|
38
|
+
|
|
39
|
+
#### Payment Methods
|
|
40
|
+
|
|
41
|
+
The synchronous and asynchronous clients now provide a `payment_methods` module that lists saved payment methods, optionally filtered by `customer_id` or `customer_email`.
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
methods = client.payment_methods.list(customer_id="cust_789")
|
|
45
|
+
print(methods.results[0].methodData["brand"], methods.results[0].methodData["last4"])
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Only payment methods with status `succeeded` are returned.
|
|
49
|
+
|
|
50
|
+
#### Transactions
|
|
51
|
+
|
|
52
|
+
The synchronous and asynchronous clients now provide a `transactions` module that lists financial transactions, including the itemized Merchant of Record fee breakdown when applicable.
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
transactions = client.transactions.list(status="success", start_date="2026-07-01")
|
|
56
|
+
print(transactions.results[0].amountTotal, transactions.results[0].morFeeBreakdown)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`client.transactions.list()` supports `search`, `status`, `start_date`, `end_date`, `page`, and `page_size` filters.
|
|
60
|
+
|
|
61
|
+
</Update>
|
|
62
|
+
|
|
63
|
+
<Update label="v2.7.4" description="September 8, 2026">
|
|
64
|
+
|
|
65
|
+
### New Features
|
|
66
|
+
|
|
67
|
+
#### Control How Subscription Updates Are Billed
|
|
68
|
+
|
|
69
|
+
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.
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from kelviq_sdk import ProrationBehavior
|
|
73
|
+
|
|
74
|
+
subscription = client.subscriptions.update(
|
|
75
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
76
|
+
planIdentifier="premium-plan",
|
|
77
|
+
chargePeriod="MONTHLY",
|
|
78
|
+
prorationBehavior=ProrationBehavior.PRORATE_NEXT_INVOICE,
|
|
79
|
+
)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The SDK validates the value and serializes it as `proration_behavior`. Omit it to use your organization's default.
|
|
83
|
+
|
|
84
|
+
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.
|
|
85
|
+
|
|
86
|
+
#### Preview Subscription Updates
|
|
87
|
+
|
|
88
|
+
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.
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
preview = client.subscriptions.preview_update(
|
|
92
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
93
|
+
planIdentifier="premium-plan",
|
|
94
|
+
chargePeriod="YEARLY",
|
|
95
|
+
prorationBehavior=ProrationBehavior.PRORATE_NEXT_INVOICE,
|
|
96
|
+
features=[{"identifier": "seats", "quantity": 10}],
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
print(preview.recurringAmount, preview.amountChargedImmediately)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The returned Pydantic models include major- and minor-unit amounts, the next payment attempt, and preview invoice line items.
|
|
103
|
+
|
|
104
|
+
#### Set a Custom Trial Period at Checkout
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
session = client.checkout.create_session(
|
|
110
|
+
planIdentifier="premium-plan",
|
|
111
|
+
chargePeriod="MONTHLY",
|
|
112
|
+
successUrl="https://example.com/checkout/success",
|
|
113
|
+
trialPeriod=14,
|
|
114
|
+
)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
#### Use a Custom Amount for One-Time Charges
|
|
118
|
+
|
|
119
|
+
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`.
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
charge = client.charges.create(
|
|
123
|
+
planIdentifier="lifetime-access",
|
|
124
|
+
chargePeriod="ONE_TIME",
|
|
125
|
+
customerId="cust_789",
|
|
126
|
+
currencyCode="USD",
|
|
127
|
+
customAmount=49.99,
|
|
128
|
+
taxBehavior="INCLUSIVE",
|
|
129
|
+
)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Changes
|
|
133
|
+
|
|
134
|
+
`successUrl` is now required when calling the synchronous or asynchronous `checkout.create_session()` method, matching the API contract.
|
|
135
|
+
|
|
136
|
+
### Deprecations
|
|
137
|
+
|
|
138
|
+
`probationBehaviour` is deprecated in favour of `prorationBehavior` (`probation` was a typo for `proration`). It is still accepted and continues to serialize as `probation_behaviour`.
|
|
139
|
+
|
|
140
|
+
</Update>
|
|
141
|
+
|
|
7
142
|
<Update label="v2.7.3" description="July 21, 2026">
|
|
8
143
|
|
|
9
144
|
### New Features
|