@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,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
  ![Kelviq release cover for June 26, 2026](/images/changelog/2026-06-26.png)
@@ -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
@@ -0,0 +1,150 @@
1
+ ---
2
+ title: "Apply a discount code at checkout"
3
+ slug: "checkout/apply-a-discount-code"
4
+ section: "checkout"
5
+ description: "Let customers enter a discount code or pre-apply one to a Kelviq checkout"
6
+ ---
7
+ Kelviq can show a discount-code field at checkout or apply a known code before the checkout page opens. Use the first option for general promotions and the second for targeted campaigns, partner offers, or customer-specific links.
8
+
9
+ ## Before you start
10
+
11
+ Create the code in **Product Catalog → Discounts** and check that it:
12
+
13
+ - is active and has not expired;
14
+ - has not reached its redemption limit;
15
+ - applies to the selected product and plan; and
16
+ - uses the same currency as the price when it is a fixed-amount discount.
17
+
18
+ [Learn how to create and restrict a discount →](/product-catalog/discounts)
19
+
20
+ ## Let the customer enter a code
21
+
22
+ When creating a checkout session through the API, set `discountsEnabled` to `true`. This shows the discount-code field so the customer can enter an eligible code.
23
+
24
+ ```json
25
+ {
26
+ "planIdentifier": "pro",
27
+ "chargePeriod": "MONTHLY",
28
+ "customerId": "cust_789",
29
+ "successUrl": "https://example.com/checkout/success",
30
+ "discountsEnabled": true
31
+ }
32
+ ```
33
+
34
+ `discountsEnabled` defaults to `true`. Set it to `false` only when you want to hide discount-code entry for that session.
35
+
36
+ ## Pre-apply a code with the Checkout API
37
+
38
+ Pass the code as `discountCode` in the JSON request body. Kelviq validates it while creating the checkout session. If the code is inactive, expired, or not valid for the selected plan, the request fails instead of creating a session with the wrong price.
39
+
40
+ ```bash cURL
41
+ curl --request POST \
42
+ --url https://sandboxapi.kelviq.com/api/v1/checkout/ \
43
+ --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
44
+ --header "Content-Type: application/json" \
45
+ --data '{
46
+ "planIdentifier": "pro",
47
+ "chargePeriod": "MONTHLY",
48
+ "customerId": "cust_789",
49
+ "successUrl": "https://example.com/checkout/success",
50
+ "discountsEnabled": true,
51
+ "discountCode": "LAUNCH20"
52
+ }'
53
+ ```
54
+
55
+ ```javascript Node.js
56
+ const response = await fetch("https://sandboxapi.kelviq.com/api/v1/checkout/", {
57
+ method: "POST",
58
+ headers: {
59
+ Authorization: `Bearer ${process.env.KELVIQ_SANDBOX_SERVER_API_KEY}`,
60
+ "Content-Type": "application/json",
61
+ },
62
+ body: JSON.stringify({
63
+ planIdentifier: "pro",
64
+ chargePeriod: "MONTHLY",
65
+ customerId: "cust_789",
66
+ successUrl: "https://example.com/checkout/success",
67
+ discountsEnabled: true,
68
+ discountCode: "LAUNCH20",
69
+ }),
70
+ });
71
+
72
+ if (!response.ok) {
73
+ throw new Error(await response.text());
74
+ }
75
+
76
+ const { checkoutUrl } = await response.json();
77
+ ```
78
+
79
+ ```python Python
80
+ import os
81
+ import requests
82
+
83
+ response = requests.post(
84
+ "https://sandboxapi.kelviq.com/api/v1/checkout/",
85
+ headers={
86
+ "Authorization": f"Bearer {os.environ['KELVIQ_SANDBOX_SERVER_API_KEY']}",
87
+ "Content-Type": "application/json",
88
+ },
89
+ json={
90
+ "planIdentifier": "pro",
91
+ "chargePeriod": "MONTHLY",
92
+ "customerId": "cust_789",
93
+ "successUrl": "https://example.com/checkout/success",
94
+ "discountsEnabled": True,
95
+ "discountCode": "LAUNCH20",
96
+ },
97
+ )
98
+ response.raise_for_status()
99
+
100
+ checkout_url = response.json()["checkoutUrl"]
101
+ ```
102
+
103
+ A successful request returns the hosted checkout URL:
104
+
105
+ ```json
106
+ {
107
+ "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
108
+ "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
109
+ }
110
+ ```
111
+
112
+ Redirect the customer to `checkoutUrl`. Before completing payment, confirm that checkout shows the code, adjusted price, currency, and billing period you expect.
113
+
114
+ ## Pre-apply a code in a static checkout link
115
+
116
+ For a static product checkout link, use the snake-case `discount_code` query parameter:
117
+
118
+ ```text
119
+ https://www.kelviq.com/buy/123e4567-e89b-12d3-a456-426614174000/?plan_identifier=pro&charge_period=MONTHLY&discounts_enabled=true&discount_code=LAUNCH20
120
+ ```
121
+
122
+ Use the product UUID shown in the Kelviq dashboard. URL-encode the code if it contains spaces or reserved characters.
123
+
124
+ The names are different by design: use `discountCode` in an API JSON body and `discount_code` in a static checkout URL.
125
+
126
+ [See all static checkout URL parameters →](/checkout/static-checkout-url)
127
+
128
+ ## Test the integration
129
+
130
+ Test the complete flow in sandbox before using a production code:
131
+
132
+ 1. Create a sandbox discount and an eligible product price.
133
+ 2. Create the checkout session with the matching sandbox API key.
134
+ 3. Open the returned checkout URL.
135
+ 4. Confirm the original price, discount, tax, and final total.
136
+ 5. Complete payment with a sandbox payment method and check the resulting order.
137
+
138
+ Do not test a small live charge on your own card. Repeated self-payments can cause the card to be blocked. Use sandbox, or use a valid 100% discount when you must inspect the production checkout without collecting a real payment.
139
+
140
+ ## Troubleshooting
141
+
142
+ | Problem | Check |
143
+ | --- | --- |
144
+ | Checkout creation fails | Confirm the code is active, unexpired, within its redemption limit, and valid for the selected plan. |
145
+ | Fixed discount is rejected | Confirm the discount currency matches the selected price currency. |
146
+ | The code field is missing | Set `discountsEnabled` or `discounts_enabled` to `true`, depending on how you create checkout. |
147
+ | The code is not pre-applied | Use `discountCode` for the API or `discount_code` for a static link. |
148
+ | Sandbox code is not found in production | Recreate the discount in production; the two environments do not share data. |
149
+
150
+ For the complete request and response schema, see [Create a checkout session API reference](/api-reference/checkout/create-a-checkout-session).