@kelviq/mcp-server 1.2.0 → 1.3.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 (111) hide show
  1. package/README.md +40 -3
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +1 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/ai/docs-for-agents.md +21 -0
  6. package/dist/docs/ai/overview.md +43 -0
  7. package/dist/docs/api-reference/authentication.md +9 -3
  8. package/dist/docs/api-reference/introduction.md +23 -2
  9. package/dist/docs/backend-integration/node-sdk.md +12 -6
  10. package/dist/docs/backend-integration/python-sdk.md +14 -8
  11. package/dist/docs/changelog.md +369 -3
  12. package/dist/docs/checkout/checkout-configuration.md +25 -75
  13. package/dist/docs/checkout/checkout-design.md +76 -0
  14. package/dist/docs/checkout/checkout-examples.md +212 -0
  15. package/dist/docs/checkout/checkout-metadata.md +1 -1
  16. package/dist/docs/checkout/custom-fields.md +60 -0
  17. package/dist/docs/checkout/embed-checkout.md +280 -0
  18. package/dist/docs/checkout/payment-methods/upi.md +69 -0
  19. package/dist/docs/checkout/payment-methods.md +119 -0
  20. package/dist/docs/checkout/static-checkout-url.md +3 -2
  21. package/dist/docs/cli/commands.md +57 -4
  22. package/dist/docs/cli/kelviq-config.md +1 -1
  23. package/dist/docs/cli/overview.md +1 -0
  24. package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
  25. package/dist/docs/customer-portal/overview.md +7 -7
  26. package/dist/docs/customer-portal/retention.md +109 -0
  27. package/dist/docs/customers-management/overview.md +105 -0
  28. package/dist/docs/frontend-integration/js-sdk.md +11 -11
  29. package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
  30. package/dist/docs/frontend-integration/react-sdk.md +8 -49
  31. package/dist/docs/frontend-integration/react-ui.md +8 -6
  32. package/dist/docs/getstarted/fees.md +27 -11
  33. package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
  34. package/dist/docs/getstarted/merchant-of-record.md +18 -24
  35. package/dist/docs/getstarted/overview.md +98 -0
  36. package/dist/docs/getstarted/review-process.md +59 -59
  37. package/dist/docs/guides/agent-toolkit.md +14 -9
  38. package/dist/docs/guides/mcp-server.md +24 -9
  39. package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
  40. package/dist/docs/guides/sandbox.md +6 -4
  41. package/dist/docs/guides/set-up-with-ai.md +43 -0
  42. package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
  43. package/dist/docs/guides/subscription-integration.md +1 -1
  44. package/dist/docs/guides/test-payments.md +640 -0
  45. package/dist/docs/guides/webhooks.md +182 -30
  46. package/dist/docs/integrations/woocommerce.md +88 -0
  47. package/dist/docs/integrations/zapier.md +22 -0
  48. package/dist/docs/legal/account-and-funds.md +59 -0
  49. package/dist/docs/legal/approved-prohibited-policy.md +32 -27
  50. package/dist/docs/legal/payment-flow-diagram.md +7 -7
  51. package/dist/docs/manifest.json +160 -41
  52. package/dist/docs/openapi.json +1359 -109
  53. package/dist/docs/payouts/overview.md +14 -12
  54. package/dist/docs/payouts/payout-account.md +1 -1
  55. package/dist/docs/payouts/transactions.md +3 -3
  56. package/dist/docs/product-catalog/create-a-feature.md +3 -3
  57. package/dist/docs/product-catalog/digital-downloads.md +5 -5
  58. package/dist/docs/product-catalog/discounts.md +2 -2
  59. package/dist/docs/product-catalog/entitlements.md +20 -27
  60. package/dist/docs/product-catalog/free-and-trials.md +5 -5
  61. package/dist/docs/product-catalog/license-keys.md +56 -29
  62. package/dist/docs/product-catalog/links.md +3 -3
  63. package/dist/docs/product-catalog/location-based-pricing.md +6 -10
  64. package/dist/docs/product-catalog/one-time-payments.md +3 -7
  65. package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
  66. package/dist/docs/product-catalog/plans.md +22 -19
  67. package/dist/docs/product-catalog/products.md +11 -3
  68. package/dist/docs/product-catalog/proration.md +69 -0
  69. package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
  70. package/dist/docs/product-catalog/subscriptions.md +52 -22
  71. package/dist/docs/product-catalog/tax-settings.md +8 -8
  72. package/dist/docs/product-catalog/usage-alerts.md +7 -7
  73. package/dist/docs/product-catalog/usage-based-billing.md +156 -29
  74. package/dist/docs/product-catalog/usage-limits.md +78 -0
  75. package/dist/docs/promotions/create-a-promotion.md +2 -2
  76. package/dist/docs/promotions/overview.md +1 -1
  77. package/dist/docs/quickstart/core-concepts.md +36 -30
  78. package/dist/docs/quickstart/dashboard-setup.md +26 -22
  79. package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
  80. package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
  81. package/dist/docs/sales/checkout-sessions.md +28 -39
  82. package/dist/docs/sales/orders.md +30 -54
  83. package/dist/docs/settings/customer-emails.md +52 -0
  84. package/dist/docs/settings/members.md +27 -0
  85. package/dist/docs/settings/profile.md +26 -0
  86. package/dist/docs/settings/zapier.md +22 -0
  87. package/dist/http/errors.d.ts +20 -1
  88. package/dist/http/errors.js +83 -31
  89. package/dist/http/errors.js.map +1 -1
  90. package/dist/schemas/kelviq.d.ts +54 -0
  91. package/dist/schemas/kelviq.js +64 -0
  92. package/dist/schemas/kelviq.js.map +1 -1
  93. package/dist/server.js +3 -2
  94. package/dist/server.js.map +1 -1
  95. package/dist/tools/_resolve.js +14 -10
  96. package/dist/tools/_resolve.js.map +1 -1
  97. package/dist/tools/features.js +9 -2
  98. package/dist/tools/features.js.map +1 -1
  99. package/dist/tools/imports.d.ts +68 -0
  100. package/dist/tools/imports.js +242 -0
  101. package/dist/tools/imports.js.map +1 -0
  102. package/dist/tools/index.d.ts +2 -1
  103. package/dist/tools/index.js +4 -1
  104. package/dist/tools/index.js.map +1 -1
  105. package/dist/tools/product-files.js +10 -3
  106. package/dist/tools/product-files.js.map +1 -1
  107. package/dist/tools/product-settings.js +10 -3
  108. package/dist/tools/product-settings.js.map +1 -1
  109. package/dist/tools/products.js +14 -4
  110. package/dist/tools/products.js.map +1 -1
  111. package/package.json +1 -1
@@ -6,6 +6,372 @@ description: "Every Kelviq release across the dashboard, API, SDKs, and develope
6
6
  ---
7
7
  import { ChangelogFilter } from "/snippets/changelog-filter.jsx";
8
8
 
9
+ <Update label="v1.27" description="November 20, 2026" tags={["API"]}>
10
+
11
+ ### New Features
12
+
13
+ #### Import a Lemon Squeezy store
14
+
15
+ One request brings a Lemon Squeezy store into your Kelviq organization: business profile, products and plans, customers, files, orders, renewals, discount codes, and license keys with their activations.
16
+
17
+ - [Start a Lemon Squeezy import](/api-reference/imports/start-a-lemon-squeezy-import) queues the import and returns `202`. It runs in the background and emails a report to the organization owner when it ends.
18
+ - Set `dryRun` to `true` to go through the whole import, save nothing, and get the same report.
19
+ - Imported plans are published and discount codes work at checkout as soon as the import finishes. Send `publishPlan: false` or `publishDiscount: false` to keep them as drafts and switched off.
20
+ - Running it again only adds what is new and picks up refunds made since.
21
+ - Subscriptions are imported as history. They keep renewing on Lemon Squeezy, and Kelviq does not charge them.
22
+
23
+ ```json
24
+ {
25
+ "apiKey": "<lemon squeezy api key>",
26
+ "storeId": "12345",
27
+ "dryRun": true,
28
+ ...
29
+ }
30
+ ```
31
+
32
+ Authenticate with a Server API Key created by the organization owner. The [migration guide](/guides/migrate-from-lemon-squeezy) walks through the whole move.
33
+
34
+ </Update>
35
+
36
+ <Update label="v0.5.0" description="November 20, 2026" tags={["CLI"]}>
37
+
38
+ ### New Features
39
+
40
+ #### Import a store from the terminal
41
+
42
+ - `kelviq import lemon-squeezy --store <id> --dry-run` previews an import of your Lemon Squeezy store: nothing is saved and a report is emailed. Without `--dry-run`, the command restates the environment, store, steps, order type and publish choices, asks, and starts the import.
43
+ - `--only` and `--skip` choose the steps and `--orders` chooses which sales. Imported plans are published and discount codes work at checkout straight away; `--no-publish-plans` and `--no-publish-discounts` keep them as drafts and switched off.
44
+ - The Lemon Squeezy key is read from `LEMONSQUEEZY_API_KEY` in your shell or env file, or typed at a masked prompt in an interactive terminal. It is never taken as a flag and never printed.
45
+ - `kelviq import` on its own lists the available sources.
46
+
47
+ See the [command reference](/cli/commands#kelviq-import).
48
+
49
+ </Update>
50
+
51
+ <Update label="v1.3.0" description="November 20, 2026" tags={["MCP Server"]}>
52
+
53
+ ### New Features
54
+
55
+ - `import_start` starts a store import from your AI assistant. Lemon Squeezy is supported, and `storeId` is required for it. `dryRun` is required, so the assistant always chooses between a preview and a real run. The tool is annotated as destructive, so clients confirm it, and its result names the environment and notes that there is nothing to poll. The server reads the Lemon Squeezy key from `LEMONSQUEEZY_API_KEY` in its environment, which keeps it out of the conversation. 57 → 58 tools.
56
+ - `checkout_create_session` accepts `customFields`, the identifiers of the [custom fields](/checkout/custom-fields) to collect at checkout.
57
+ - `webhook_endpoint_create` and `webhook_endpoint_update` accept `name` and `description`.
58
+ - Validation errors from the API now show the field and the reason in the tool result.
59
+
60
+ </Update>
61
+
62
+ <Update label="v1.26" description="November 9, 2026" tags={["API"]}>
63
+
64
+ ### Improvements
65
+
66
+ #### Richer webhook endpoints
67
+
68
+ [Webhook endpoints](/api-reference/webhook-endpoints/list-webhook-endpoints) accept an optional `name` (defaults to the URL's host) and `description` on create and update, and `events` must now contain at least one type. Each endpoint in a response carries `status` (`active`, `failing` or `disabled`), `deliveryCount` for the period given by `start_date` / `end_date` (default: last 7 days), `recentDeliveries` (outcome of the last eight), `lastDelivery`, `verifiedAt`, `secretPreview`, `createdOn` and `createdByName`. The list call takes `search`, `status` and `ordering` (`created_on`, `name` or `last_delivery`).
69
+
70
+ #### Per-attempt webhook logs
71
+
72
+ Each row in [List webhook logs](/api-reference/webhooks/list-webhook-logs) now describes one delivery attempt, with `attemptNumber`, `maxAttempts`, `willRetry`, `nextRetryAt`, `durationMs`, `responseBody`, `endpointName` and `isTest`. New filters: `status` (`delivered` or `failed`), `endpoint`, `event_type`, `search` (an event ID or its leading characters), `test`, and `latest_only` for one row per event.
73
+
74
+ #### Subscription start date on orders and invoices
75
+
76
+ The `subscription` summary on [orders](/api-reference/orders/list-orders) and [invoices](/api-reference/invoices/list-invoices) now includes `startDate`, `startDateTime` and `trialDaysRemaining`.
77
+
78
+ ```json
79
+ "subscription": {
80
+ "startDate": "2026-08-01",
81
+ "startDateTime": "2026-08-01T10:14:22Z",
82
+ "nextInvoiceDate": "2026-08-28T10:46:34Z",
83
+ "trialDaysRemaining": 0
84
+ }
85
+ ```
86
+
87
+ </Update>
88
+
89
+ <Update label="v1.25" description="November 3, 2026" tags={["API"]}>
90
+
91
+ ### Improvements
92
+
93
+ #### Timezone-aware date range filters
94
+
95
+ The `start_date` / `end_date` query params on the orders, transactions, refunds, webhook logs and checkout session list endpoints now also accept an ISO 8601 datetime with a UTC offset, so a client in another timezone can filter on its own local day even though records are stored in UTC.
96
+
97
+ ```
98
+ GET /api/v1/orders/?start_date=2026-11-03T00:00:00%2B05:30&end_date=2026-11-04T00:00:00%2B05:30
99
+ ```
100
+
101
+ A datetime `start_date` is inclusive and a datetime `end_date` is exclusive, so local midnight-to-midnight returns exactly one local day. Plain `YYYY-MM-DD` values keep working as inclusive UTC calendar days. Remember to URL-encode `+` as `%2B`; the API also tolerates an unencoded offset.
102
+
103
+ </Update>
104
+
105
+ <Update label="v1.24" description="October 30, 2026" tags={["API"]}>
106
+
107
+ ### New Features
108
+
109
+ #### Retention offers in the API
110
+
111
+ Two new endpoints let you build the cancellation flow, with retention offers, in your own app instead of the customer portal:
112
+
113
+ - [Get retention offers](/api-reference/subscriptions/get-retention-offers) returns every cancellation reason with the offer configured for it (discount, pause or support) and whether the subscription is eligible for it right now.
114
+ - [Accept a retention offer](/api-reference/subscriptions/accept-a-retention-offer) applies the offer the customer chose: attaches the discount, pauses the subscription, or returns the support link.
115
+
116
+ ```json
117
+ {
118
+ "offerType": "PAUSE",
119
+ "cancellationFeedback": "UNUSED",
120
+ "pauseMonths": 3
121
+ }
122
+ ```
123
+
124
+ Offers are configured in the dashboard retention settings. See [Retention offers](/product-catalog/subscriptions#retention-offers) for the flow.
125
+
126
+ </Update>
127
+
128
+ <Update label="v1.23" description="October 30, 2026" tags={["App"]}>
129
+
130
+ ## Custom fields
131
+
132
+ Ask customers your own questions at checkout, such as a company name for the invoice, a purchase order number, or agreement to your terms.
133
+
134
+ <img width="480" src="/images/settings/custom-field-create.webp" alt="Creating a required Company name custom field" />
135
+
136
+ Create a field in **Settings → Custom fields** and pick its type: text, number, yes/no, email, dropdown, URL, or date. Make it required, add help text and a placeholder, and set limits such as length, a pattern, or a date range. Customers see your error message if an answer doesn't pass.
137
+
138
+ Add the field to a checkout link from **Get Link** on the product page, or pass it in `customFields` when you create a checkout session. Answers are saved with the order and subscription, and sent in your webhooks.
139
+
140
+ Read [Custom fields](/checkout/custom-fields) to set one up.
141
+
142
+ </Update>
143
+
144
+ <Update label="v1.22" description="October 23, 2026" tags={["App"]}>
145
+
146
+ ## Retention offers
147
+
148
+ Customers who cancel in the customer portal can now get an offer to stay. Kelviq asks why they're leaving, then shows the offer you picked for that reason.
149
+
150
+ <img src="/images/retention/retention-pause-offer.webp" alt="A retention offer to pause the subscription for 1, 3, or 6 months" />
151
+
152
+ Set up three kinds of offer in **Settings → Retention**:
153
+
154
+ * **Discount:** a percentage off the next few payments.
155
+ * **Pause:** 1, 3, or 6 months without billing.
156
+ * **Support:** a link to a booking page, live chat, or your help site.
157
+
158
+ Then match each cancellation reason to an offer, such as a discount for "Too expensive" or a pause for "Not using it enough". You can also ask one optional question before the customer confirms, and choose whether an offer can be accepted more than once.
159
+
160
+ Read [Retention offers](/customer-portal/retention) to set it up.
161
+
162
+ ## Pause and resume subscriptions
163
+
164
+ Customers can now pause their subscription from the customer portal, when a retention offer includes a pause. A paused subscription isn't billed and its entitlements are off until it resumes. Choose in **Settings → Retention → Advanced settings** whether resuming charges a full period on the spot or waits for the original billing day.
165
+
166
+ Read [Pause a subscription](/product-catalog/subscriptions#pause-a-subscription).
167
+
168
+ ## Set up with AI starts in sandbox
169
+
170
+ Open **Settings → Set up with AI** in production and the page now suggests starting in sandbox, with a **Switch to sandbox** button. Your agent builds and tests there with test cards, and `kelviq promote` copies the catalog to production when it's ready. If you stay in production, the prompt has the agent confirm before creating anything and stop at the checkout page instead of paying. Read [Set up with AI](/guides/set-up-with-ai).
171
+
172
+ ## A discount in the final abandoned cart reminder
173
+
174
+ The last [abandoned cart](/sales/abandoned-cart-recovery) reminder can now offer a percentage off the checkout total. Turn it on in **Settings → Customer emails** and set the percentage. It isn't offered when another discount already applies to the product.
175
+
176
+ ## Settings, regrouped
177
+
178
+ Settings now has four groups so related pages sit together: **Account** (Profile), **Organization** (Members, Business details, Tax settings), **Checkout & subscriptions** (Checkout design, Custom fields, Subscription proration, Customer emails, Retention), and **Developers** (Set up with AI, API keys, Webhooks, Integrations). **Notifications** is now **Customer emails**. Nothing moved out of Settings and no setting changed.
179
+
180
+ </Update>
181
+
182
+ <Update label="v1.9.0" description="October 23, 2026" tags={["API"]}>
183
+
184
+ ### New Features
185
+
186
+ #### Webhooks
187
+
188
+ `subscription.paused` and `subscription.resumed`, sent whichever surface the change came from. Renewals skipped during a pause send no events.
189
+
190
+ #### Retention settings
191
+
192
+ `GET` and `PATCH /api/v1/organizations/retention-settings/` read and update the offers, the reason-to-offer map, written feedback, and the resume and repeat policies. The customer portal API gains `…/retention/` to load the offers for a subscription and `…/retention/accept/` to accept one. The cancel endpoint accepts an optional `offerType` to record an offer the customer declined.
193
+
194
+ #### SDKs
195
+
196
+ `entitlements.invalidateCache` (Node) and `entitlements.invalidate_cache` (Python) drop a customer's cached entitlements, for use in `subscription.paused` and `subscription.cancelled` handlers.
197
+
198
+ See [Pause a subscription](/product-catalog/subscriptions#pause-a-subscription) and [Retention offers](/customer-portal/retention).
199
+
200
+ </Update>
201
+
202
+ <Update label="v1.21" description="October 16, 2026" tags={["App"]}>
203
+
204
+ ## Set up with AI
205
+
206
+ Billing is now something you can hand to your coding agent. The new **Settings → Set up with AI** page writes a prompt for Claude Code, Cursor, Codex, Lovable, Replit, Bolt, or any agent that can edit files and run commands, and you paste it in as your first message.
207
+
208
+ <img src="/images/set-up-with-ai-integrate.webp" alt="The Set up with AI page with its three steps and the prompt it generates" />
209
+
210
+ Pick one of two paths. **Integrate with my app** connects the plans you have already published: the agent adds checkout, the billing portal, feature checks, and a verified webhook route, and registers the webhook when your app has a public URL. **Set up everything** starts earlier. The agent reads your app, proposes plans, prices, limits, license keys and discount codes, and only creates them in your sandbox after you approve.
211
+
212
+ Describe what you want in plain language, or add a common request such as a monthly and yearly toggle or a 7-day free trial, and the prompt includes it.
213
+
214
+ Your keys never go in the chat. The page gives you a block to paste into your project's `.env.local`, and the agent reads them from the file. Build and test with sandbox keys, or set it up directly in production. Business verification and your keys stay with you.
215
+
216
+ ## Checkout design
217
+
218
+ Make checkout look like the rest of your product. **Settings → Checkout design** has your logo, colors, and corner radius in one place, with a live preview next to the controls.
219
+
220
+ <img src="/images/checkout-design/checkout-design-settings.webp" alt="The Checkout design settings page with a live preview" />
221
+
222
+ Change any color for light and dark mode, set how rounded cards and buttons are, and choose whether checkout opens light, dark, or matching the buyer's device. You can also hide parts of checkout you don't need, such as product images or the discount code field. Read [Checkout design](/checkout/checkout-design) for every setting.
223
+
224
+ ## Fixes
225
+
226
+ * Amounts show two decimal places everywhere in the dashboard.
227
+ * In promotion settings, the security options are now off for new promotions.
228
+
229
+ </Update>
230
+
231
+ <Update label="v1.20" description="October 9, 2026" tags={["App"]}>
232
+
233
+ ## New checkout
234
+
235
+ Every checkout link and checkout session now opens in a redesigned page.
236
+
237
+ <img src="/images/checkout-design/checkout-design-light-dark.webp" alt="The new checkout in light mode and in dark mode" />
238
+
239
+ Checkout follows the customer's device setting for light or dark mode, and a switch in the corner lets them change it. Plans, billing periods, included features, promotion codes, tax, and business purchases are all on the one page.
240
+
241
+ See every variation on the [Checkout examples](/checkout/checkout-examples) page, and change the look in [Checkout design](/checkout/checkout-design).
242
+
243
+ </Update>
244
+
245
+ <Update label="v1.19" description="October 2, 2026" tags={["App"]}>
246
+
247
+ ## Choose how plan changes are billed
248
+
249
+ When a customer moves between plans mid-period, you decide what happens to the partial period. **Settings → Subscription proration** has two defaults:
250
+
251
+ <img src="/images/subscription-proration-settings.webp" alt="The Subscription proration settings page with defaults for plan changes and plan version migrations" />
252
+
253
+ * **Plan upgrades and downgrades** defaults to **Immediate charge**: Kelviq prorates the difference and invoices it right away.
254
+ * **Plan version migrations** defaults to **Prorate on next invoice**: the change applies now and the difference lands on the next renewal.
255
+
256
+ Both accept a third option, **No proration**, which changes the plan without crediting or charging for the partial period. Switching between monthly and yearly billing always invoices immediately, whatever you choose here. API requests that pass `prorationBehavior` override these defaults.
257
+
258
+ [Subscriptions](/product-catalog/subscriptions#control-how-a-change-is-billed) explains each option with an example.
259
+
260
+ </Update>
261
+
262
+ <Update label="v1.18" description="September 4, 2026" tags={["App"]}>
263
+
264
+ ## Abandoned cart recovery
265
+
266
+ Kelviq now follows up with customers who start a checkout but do not pay. When a checkout sits untouched for an hour, Kelviq marks it as abandoned and sends up to three reminder emails, one each day for three days. Each email carries a **Return to checkout** link that takes the customer back to their session. The checkout expires four days after it was created.
267
+
268
+ You do not need to set anything up. Recovery emails are on by default for every organization, and you can turn them off with the **Abandoned cart recovery** toggle in **Settings → Notifications**. Reminders are only sent when there is a customer email to send them to, and a customer is never emailed twice for the same step. A customer who starts several checkouts gets one set of reminders, not one per checkout.
269
+
270
+ Read [Abandoned cart recovery](/sales/abandoned-cart-recovery) for the full schedule, the abandonment rules, and what happens at expiration.
271
+
272
+ </Update>
273
+
274
+ <Update label="v1.8.3" description="October 15, 2026" tags={["API"]}>
275
+
276
+ ### Improvements
277
+
278
+ #### Custom field responses in webhooks
279
+
280
+ The `checkout.completed`, `order.created`, `order.updated`, and `order.refunded` webhook payloads now include `custom_fields_data` in `data.object`: the customer's responses to the custom fields collected during checkout, keyed by field identifier. The object is empty when no custom fields were collected.
281
+
282
+ ```json
283
+ "custom_fields_data": {
284
+ "company-name": "Acme Inc",
285
+ "purchase-order-number": "PO-4821"
286
+ }
287
+ ```
288
+
289
+ See [Webhooks](/guides/webhooks#custom-field-responses) for details.
290
+
291
+ </Update>
292
+
293
+ <Update label="v1.8.2" description="October 13, 2026" tags={["API"]}>
294
+
295
+ ### New Features
296
+
297
+ #### Custom fields in checkout sessions
298
+
299
+ The [Create a checkout session](/api-reference/checkout/create-a-checkout-session) endpoint now documents the `customFields` request property. Pass an array of custom field identifiers to display those fields during checkout and collect validated responses from the customer:
300
+
301
+ ```json
302
+ {
303
+ "planIdentifier": "pro-plan",
304
+ "chargePeriod": "MONTHLY",
305
+ "successUrl": "https://example.com/success",
306
+ "customFields": ["company-name", "purchase-order-number"]
307
+ }
308
+ ```
309
+
310
+ Only active custom fields configured for the authenticated organization are included, and they appear in their configured sort order.
311
+
312
+ </Update>
313
+
314
+ <Update label="v1.8.1" description="October 5, 2026" tags={["API"]}>
315
+
316
+ ### Improvements
317
+
318
+ #### Webhook retries on server errors and rate limits
319
+
320
+ Kelviq now retries a webhook delivery when your endpoint returns a `5xx` status code or `429 Too Many Requests`. Previously, only network failures and timeouts were retried, so an endpoint that was briefly unavailable or rate limiting lost the delivery after one attempt.
321
+
322
+ Retries follow the existing schedule: up to `3` retries, `60` seconds apart. Each attempt appears in the delivery logs with its status code. Other `4xx` and `3xx` responses are still treated as final and are not retried.
323
+
324
+ See [Webhooks](/guides/webhooks#how-it-works) for details.
325
+
326
+ </Update>
327
+
328
+ <Update label="v1.8.0" description="September 27, 2026" tags={["API"]}>
329
+
330
+ ### New Features
331
+
332
+ #### Per-organization rate limits
333
+
334
+ Requests to endpoints authenticated with a Server or Client API Key are now rate limited per organization: `500 requests` / minute in production, `100 requests` / minute in sandbox. A Server and Client API Key belonging to the same organization share one quota.
335
+
336
+ Exceeding the limit returns a `429 Too Many Requests` response with a `Retry-After` header naming how many seconds to wait before retrying:
337
+
338
+ ```json
339
+ {
340
+ "detail": "Request was throttled. Expected available in 42 seconds."
341
+ }
342
+ ```
343
+
344
+ The limit only applies to requests authenticated with your own API keys.
345
+
346
+ See [Rate limits](/api-reference/introduction#rate-limits) for details.
347
+
348
+ </Update>
349
+
350
+ <Update label="v0.4.2" description="September 23, 2026" tags={["CLI"]}>
351
+
352
+ ### Fixes
353
+
354
+ - `kelviq pull` no longer fails on a plan that grants unlimited usage of a feature. The dashboard stores an empty `value` for those entitlements, which the config format rejected. Pull now writes them as `hasUnlimitedUsage: true` with no `value`.
355
+
356
+ </Update>
357
+
358
+ <Update label="v0.4.1" description="September 18, 2026" tags={["CLI"]}>
359
+
360
+ ### Fixes
361
+
362
+ - `kelviq discount create --product <identifier>` now finds the product. It looks the identifier up through the product list, since the product endpoint itself takes only a UUID.
363
+
364
+ </Update>
365
+
366
+ <Update label="v1.2.1" description="September 18, 2026" tags={["MCP Server"]}>
367
+
368
+ ### Fixes
369
+
370
+ - Product and feature identifiers now resolve correctly in every tool that accepts them. 1.2.0 looked them up through the retrieve endpoints, which take only a UUID, so any identifier failed with a 404.
371
+ - `product_retrieve`, `product_update`, `product_archive`, the product settings and image tools, `feature_retrieve` and `feature_archive` accept an identifier as well as a UUID.
372
+
373
+ </Update>
374
+
9
375
  <Update label="v0.4.0" description="September 16, 2026" tags={["CLI"]}>
10
376
 
11
377
  ### New Features
@@ -108,7 +474,7 @@ chargeCatalogPrice: [
108
474
  ]
109
475
  ```
110
476
 
111
- Previously that field held the whole feature object the API returns — its UUID, timestamps and Stripe ids — and each charge carried its own server-generated ids. Those fields are now left out, so a pulled catalog is around 20% smaller, holds no UUIDs or Stripe ids, and reads as something you can edit by hand and review in a pull request.
477
+ Previously that field held the whole feature object the API returns — its UUID, timestamps and other ids — and each charge carried its own server-generated ids. Those fields are now left out, so a pulled catalog is around 20% smaller, holds no UUIDs or other ids, and reads as something you can edit by hand and review in a pull request.
112
478
 
113
479
  Existing pulled files keep working: `kelviq push` accepts the identifier, the UUID and the embedded object alike.
114
480
 
@@ -720,7 +1086,7 @@ The response includes the new recurring amount, any amount that would be charged
720
1086
 
721
1087
  #### Trial ending webhook
722
1088
 
723
- 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`.
1089
+ You can now subscribe to `subscription.trial_will_end`. Kelviq sends this a few days before a subscription's trial ends. 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`.
724
1090
 
725
1091
  </Update>
726
1092
 
@@ -738,7 +1104,7 @@ You can now list and retrieve invoices directly, rather than only receiving them
738
1104
  The invoice object also has three new fields, matching what's already sent in invoice webhooks:
739
1105
 
740
1106
  - `attemptCount` — number of payment attempts made against the invoice.
741
- - `nextPaymentAttempt` — when Stripe will next retry collection, if a retry is scheduled.
1107
+ - `nextPaymentAttempt` — when will next retry collection, if a retry is scheduled.
742
1108
  - `failureDetails` — `code`, `message`, and `paymentMethodType` for the most recent failed payment attempt. `null` once the invoice is paid.
743
1109
 
744
1110
  #### Filter subscriptions by modification date
@@ -9,21 +9,21 @@ Checkout in Kelviq allows you to collect payments from customers. You can genera
9
9
  ## Overview
10
10
  Kelviq's checkout system:
11
11
  - **Powers your sales** - Collect payments and create customer subscriptions
12
- - **Integrates with Stripe** - Uses Stripe as the payment processor
12
+ - **Many payment methods** - Cards, wallets, bank payments, and local methods
13
13
  - **Highly configurable** - Control plans, pricing, trial periods, and more
14
14
  - **Multi-currency ready** - Support customers worldwide
15
- - **Easy to embed** - Generate links for any product and plans
15
+ - **Easy to embed** - Generate links for any product and plans, or [embed checkout on your own site](/checkout/embed-checkout)
16
16
 
17
17
  ## Generating Checkout Links
18
18
 
19
19
  Checkout links are generated at the **product level**. Each link can include one or more plans.
20
20
 
21
- <img height="200" src="/images/accessing-checkout.png" />
21
+ <img src="/images/accessing-checkout.webp" />
22
22
 
23
23
  ### Quick Start
24
24
 
25
25
  1. **Go to Products** → Select your product
26
- 2. **Click "Generate Checkout Link"** → Opens the link builder
26
+ 2. **Click "Get Link"** → Opens the link builder
27
27
  3. **Select plans** → Choose which plans to include
28
28
  4. **Configure options** → Set defaults and features
29
29
  5. **Copy link** → Share with customers
@@ -36,7 +36,7 @@ A production checkout link starts with your product UUID:
36
36
  https://www.kelviq.com/buy/{PRODUCT_UUID}/
37
37
  ```
38
38
 
39
- Sandbox links use `https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/`. Copy the link from the dashboard so the environment and product UUID are correct. The old product identifier is not used in checkout URLs.
39
+ Sandbox links use `https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/`. Copy the link from the dashboard so the environment and product UUID are correct.
40
40
 
41
41
  Add query parameters to control what the customer sees:
42
42
 
@@ -69,7 +69,7 @@ Include multiple plans in a single checkout to let customers choose their tier.
69
69
  **Plans Configuration**
70
70
  - Select which plans are enabled (shown to customer)
71
71
  - Choose a recommended plan (highlighted by default)
72
- - Cannot disable all plans
72
+ - At least one plan stays enabled
73
73
  - Disabled plans don't appear in checkout
74
74
 
75
75
  ### Example: Multi-Plan Pricing
@@ -141,7 +141,7 @@ Plan: Basic
141
141
 
142
142
  Plan: Pro
143
143
  ├─ Monthly: $29/month
144
- └─ Yearly: $290/year (2.5% discount vs monthly)
144
+ └─ Yearly: $290/year (17% discount vs monthly)
145
145
 
146
146
  Plan: Enterprise
147
147
  ├─ Monthly: $99/month
@@ -257,7 +257,7 @@ const { checkoutUrl } = await response.json();
257
257
 
258
258
  Allow customers to apply discount codes at checkout:
259
259
 
260
- <img height="200" src="/images/generate-checkout-discounts.png" />
260
+ <img src="/images/generate-checkout-discounts.webp" />
261
261
 
262
262
  ```
263
263
  Customer at checkout:
@@ -273,16 +273,10 @@ Discount codes are applied automatically if the customer enters a valid code.
273
273
 
274
274
  ### Tax Collection
275
275
 
276
- Kelviq can collect and handle taxes:
276
+ Kelviq calculates and collects tax on every checkout, based on the customer's location.
277
277
 
278
- **Tax ID Collection:**
279
- - Customers can enter their tax ID (VAT number, EIN, etc.)
280
- - Used to determine applicable taxes
281
- - Required for some jurisdictions
282
-
283
- **Configuration:**
284
- - Enable/disable tax collection per product
285
- - Taxes are calculated based on customer location and tax ID
278
+ - Business customers can enter a VAT number or other tax ID. When it's valid, Kelviq applies the reverse charge.
279
+ - Choose per plan whether listed prices include tax or tax is added at checkout. See [Tax settings](/product-catalog/tax-settings).
286
280
 
287
281
  ### Country Restrictions
288
282
 
@@ -295,47 +289,9 @@ Plan: Premium Tier
295
289
  └─ Checkout effect: Plan hidden for customers in restricted countries
296
290
  ```
297
291
 
298
- ## Checkout Session Lifecycle
299
-
300
- Checkout sessions track the state of each checkout attempt:
301
-
302
- ### Session States
303
-
304
- ```
305
- open
306
- ├─ Customer is in checkout
307
- ├─ No payment yet
308
- └─ Session expires after 24 hours
309
-
310
- ↓
311
-
312
- success
313
- ├─ Payment completed
314
- ├─ Customer created (if new)
315
- ├─ Subscription created
316
- └─ Files and licenses delivered
317
-
318
- OR
319
-
320
- closed
321
- ├─ Customer abandoned checkout
322
- ├─ No payment processed
323
- ├─ Customer can restart
324
- └─ Session expired
325
- ```
326
-
327
- ### Monitoring Checkouts
328
-
329
- View checkout sessions in the dashboard:
330
-
331
- <img height="200" src="/images/checkout-sessions.png" />
292
+ ## Checkout session lifecycle
332
293
 
333
- 1. **Go to Sales** → Checkout sessions
334
- 2. **View sessions** → See all active and completed checkouts
335
- 3. **Filter by status** → Open, Success, Closed, Expired
336
- 4. **Conversion metrics** → Track conversion rates
337
-
338
- <img height="200" src="/images/checkout-sessions-detials.png" />
294
+ Each checkout attempt is a session with one of five statuses: **Open**, **Processing**, **Success**, **Closed**, or **Expired**. An unpaid session expires four days after it's created. [Checkout sessions](/sales/checkout-sessions) explains each status and how to read a session's timeline in the dashboard.
339
295
 
340
296
  ### Create Checkout Sessions via API
341
297
 
@@ -426,17 +382,7 @@ Link: ?enabled=free,premium
426
382
 
427
383
  ## Payment Methods
428
384
 
429
- Kelviq uses **Stripe** as its payment processor. Stripe supports:
430
-
431
- - **Credit/Debit Cards** - Visa, Mastercard, American Express, Discover
432
- - **Digital Wallets** - Apple Pay, Google Pay
433
- - **UPI and UPI AutoPay** - UPI payments and recurring subscription mandates for eligible customers in India
434
- - **Bank Transfers** - ACH, SEPA, etc. (regional)
435
- - **Local Methods** - iDEAL, Bancontact, Giropay, EPS (regional)
436
-
437
- Customers select their preferred payment method at checkout.
438
-
439
- Payment method availability depends on customer location and Stripe's local support. Cards are universally supported.
385
+ Checkout shows the payment methods available for the customer's location and currency: cards, wallets such as Apple Pay and Google Pay, bank payments, and local methods. Cards work everywhere. See [Payment methods](/checkout/payment-methods) for the full list.
440
386
 
441
387
  ### Does Kelviq support UPI AutoPay?
442
388
 
@@ -470,24 +416,26 @@ Plan: Pro
470
416
  └─ AUD: A$45/month
471
417
  ```
472
418
 
473
- ### Regional Pricing
419
+ ### Price localization
474
420
 
475
- Offer different prices based on customer location (PPP - Purchasing Power Parity):
421
+ A plan can have a fixed price in other currencies. Buyers get the price for where they are when checkout opens:
476
422
 
477
423
  ```
478
- Plan: Professional ($29 in US)
479
- ├─ India: ₹599 (auto-adjusted for PPP)
480
- ├─ Brazil: R$99
481
- └─ US: $29
424
+ Plan: Professional
425
+ ├─ US: $29
426
+ ├─ India: ₹599
427
+ └─ Brazil: R$99
482
428
  ```
483
429
 
430
+ You set each amount yourself. See [Location-based pricing](/product-catalog/location-based-pricing). To give a percentage off by country instead, use [Promotions](/promotions/overview).
431
+
484
432
  ## Testing Checkout
485
433
 
486
434
  ### Sandbox Testing
487
435
 
488
436
  Test checkouts without processing real payments:
489
437
 
490
- 1. **Use Stripe test cards** → Use 4242 4242 4242 4242
438
+ 1. **Use a test card** → Use 4242 4242 4242 4242
491
439
  2. **Test various scenarios** → Successful payment, declined card, etc.
492
440
  3. **Monitor test checkouts** → View in your dashboard
493
441
 
@@ -498,3 +446,5 @@ Test checkouts without processing real payments:
498
446
  | 4242 4242 4242 4242 | Successful payment |
499
447
  | 4000 0000 0000 0002 | Card declined |
500
448
  | 4000 0025 0000 3155 | Requires authentication |
449
+
450
+ Every other scenario, from specific decline reasons to wallets, SEPA Direct Debit and UPI, is listed in [Test payments](/guides/test-payments).
@@ -0,0 +1,76 @@
1
+ ---
2
+ title: "Checkout design"
3
+ slug: "checkout/checkout-design"
4
+ section: "checkout"
5
+ description: "Match checkout to your brand with your logo, colors, and the sections you want customers to see"
6
+ ---
7
+ **Settings → Checkout design** controls how every checkout for your business looks. The preview on the right updates as you make changes, and the changes apply to all checkout links and checkout sessions when you save.
8
+
9
+ <img src="/images/checkout-design/checkout-design-settings.webp" alt="Branding, Editing, and Theme settings on the Checkout design page" />
10
+
11
+ ## Branding
12
+
13
+ | Setting | What it changes |
14
+ | --- | --- |
15
+ | Business name | The name shown at the top of checkout |
16
+ | Logo | Shown at the top of checkout. Upload a **Dark mode logo** if your logo doesn't read well on a dark background |
17
+ | Logo height | Size of the logo, in pixels |
18
+ | Favicon | The icon in the browser tab |
19
+ | Background image | An image behind the checkout page |
20
+
21
+ ## Theme and colors
22
+
23
+ Checkout starts on the **Kelviq** theme. Change any color and it becomes **Custom**.
24
+
25
+ Light and dark mode each have their own set of colors. Under **Editing**, pick which one you're changing. This only affects the editor, not what customers see.
26
+
27
+ <img src="/images/checkout-design/checkout-design-theme-colors.webp" alt="The Editing toggle, theme picker, and brand colors" />
28
+
29
+ <br />
30
+
31
+ <img src="/images/checkout-design/checkout-design-light-dark.webp" alt="The same checkout in light and dark mode" />
32
+
33
+ | Group | Colors |
34
+ | --- | --- |
35
+ | Brand | Primary (buttons and the selected plan), Primary text (text on buttons) |
36
+ | Backgrounds | Product panel, Payment panel, Raised surface, Selected plan, Subtle fill, Billing period track |
37
+ | Inputs | Input background, Focus ring, Focus glow |
38
+ | Text | Text, Muted text, Placeholder text, Disabled text |
39
+ | Borders | Input border, Dividers, Plan card border |
40
+ | Status | Error, Success, Warning |
41
+
42
+ Keep enough contrast between **Primary** and **Primary text**. The button label sits on the primary color.
43
+
44
+ ## Shape
45
+
46
+ Set how rounded cards, buttons, and inputs are. Tick **Link card, button, and input radius** to use one value for all three, or untick it to set **Corner radius**, **Button radius**, and **Input radius** separately.
47
+
48
+ ## Default mode
49
+
50
+ Choose how checkout opens: **Match buyer's device**, **Light**, or **Dark**. Customers can still switch modes themselves from the corner of the page.
51
+
52
+ ## Choose what customers see
53
+
54
+ Under **Visibility**, turn sections of checkout on or off. Everything is on by default except **Metered features**.
55
+
56
+ <img src="/images/checkout-design/checkout-design-visibility.webp" alt="The Visibility checklist with every section on except metered features" />
57
+
58
+ | Section | Shows |
59
+ | --- | --- |
60
+ | Logo | Your logo at the top |
61
+ | Heading | The product name |
62
+ | Product description | The text under the product image |
63
+ | Product images | The images you added to the product |
64
+ | Plan selector | The list of plans and the billing-period tabs |
65
+ | Metered features | Usage included in the plan and its usage rates, such as credits and the price per 1,000 after that |
66
+ | Included features | The plan's features and limits |
67
+ | Discount code field | The **Add promotion code** field |
68
+ | Price breakdown | Subtotal, discount, and tax lines above the total |
69
+
70
+ Hiding the plan selector only hides the list. Checkout still uses the plan from the link. To hide the discount field for one link rather than every checkout, add `discounts_enabled=false` to the [checkout URL](/checkout/static-checkout-url).
71
+
72
+ ## Related documentation
73
+
74
+ - [Checkout examples](/checkout/checkout-examples)
75
+ - [Customize a static checkout URL](/checkout/static-checkout-url)
76
+ - [Products](/product-catalog/products)