@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
@@ -0,0 +1,405 @@
1
+ ---
2
+ title: "Migrate from Lemon Squeezy"
3
+ slug: "guides/migrate-from-lemon-squeezy"
4
+ section: "guides"
5
+ description: "Import your Lemon Squeezy store into Kelviq, start selling on Kelviq, and plan what happens to your existing subscribers."
6
+ ---
7
+ Kelviq imports your Lemon Squeezy store for you. Your products, plans, customers, order history, discount codes, files, and license keys arrive in your Kelviq organization. Your plans are published and your discount codes work at checkout, so they are ready to sell as soon as the import finishes. A report is emailed to you at the end.
8
+
9
+ ---
10
+
11
+ ## Four ways to move
12
+
13
+ Each one runs the same import on Kelviq's servers and ends with the same report in your inbox. Pick whichever suits you.
14
+
15
+
16
+
17
+ One command in your terminal: `kelviq import lemon-squeezy --store 12345`
18
+
19
+
20
+
21
+
22
+ One sentence to your coding agent: *"Import my Lemon Squeezy store into Kelviq."* It can add the Kelviq code to your app as well.
23
+
24
+
25
+
26
+
27
+ One `POST` request from your backend or terminal.
28
+
29
+
30
+
31
+
32
+ Share a Lemon Squeezy API key made for the move, and our team imports and sets up your store.
33
+
34
+
35
+ Whichever you pick, start with a dry run: the whole import is rehearsed, nothing is saved, and the report shows what a real run would do. The rest of this guide covers what the import brings over, how to run it, and how to move your app.
36
+
37
+ ---
38
+
39
+ ## Where your existing customers stand
40
+
41
+ The move happens on two tracks, and you can start the first one today.
42
+
43
+ | | What happens |
44
+ | --- | --- |
45
+ | **New sales** | Go through Kelviq as soon as your app points at Kelviq checkout. The import publishes your plans. |
46
+ | **Existing subscriptions** | Are imported as history. They keep renewing on Lemon Squeezy until it stops processing payments on March 31, 2027. Kelviq does not charge them. |
47
+
48
+ Your customers are not emailed during the import, and no webhooks fire for imported records. Nothing changes for a buyer until you change your app.
49
+
50
+ To keep those subscribers paying after March 31, 2027, do one of two things: have Kelviq move them (write to [hi@kelviq.com](mailto:hi@kelviq.com)), or have them subscribe again on Kelviq before their last Lemon Squeezy renewal.
51
+
52
+ To move active subscriptions and saved cards so that renewals continue on Kelviq, write to [hi@kelviq.com](mailto:hi@kelviq.com) before you choose a destination in Lemon Squeezy's migration form. Lemon Squeezy only lets subscriptions paid by card move to another provider.
53
+
54
+ ---
55
+
56
+ ## Key dates
57
+
58
+ These dates are Lemon Squeezy's published schedule.
59
+
60
+ | Date | What happens |
61
+ | --- | --- |
62
+ | November 16, 2026 | Lemon Squeezy stopped accepting new stores. |
63
+ | Mid-January 2027 | Lemon Squeezy's recommended latest date to start moving. |
64
+ | March 31, 2027 | Lemon Squeezy stops processing payments, including subscription renewals. |
65
+
66
+ Export anything you want to keep from Lemon Squeezy before March 31, 2027. The import below copies your sales history into Kelviq, so it is worth running well ahead of that date. Allow time for Kelviq's [business review](/getstarted/review-process) as well: it has to finish before you can take live payments.
67
+
68
+ ---
69
+
70
+ ## What the import brings over
71
+
72
+ The import runs as eight steps, in this order. You can run all of them or pick a subset.
73
+
74
+ | Step | What arrives in Kelviq |
75
+ | --- | --- |
76
+ | `store` | Your organization name, and the website, logo and country on your business profile. Fields you have already filled in are left alone. |
77
+ | `products` | Your products, and one [plan](/product-catalog/plans) for each Lemon Squeezy variant, with its price, trial, license settings and links. |
78
+ | `customers` | Your customers. One whose email already exists in your organization is linked, not duplicated. |
79
+ | `files` | Each variant's downloadable files, attached to its plan as [digital downloads](/product-catalog/digital-downloads). |
80
+ | `orders` | Orders with their invoices, and the subscription record behind each paid order. |
81
+ | `renewals` | Subscription renewal payments, as renewal orders with invoices. |
82
+ | `discounts` | [Discount codes](/product-catalog/discounts) with their limits and redemption counts. |
83
+ | `licenses` | [License keys](/product-catalog/license-keys) and their activations. |
84
+
85
+ Later steps build on earlier ones: `orders` needs `products`, and `renewals` and `licenses` need `orders`. A license key is imported only if its order was.
86
+
87
+ Not part of the import: affiliate programs, email subscriber lists, and storefront pages.
88
+
89
+ ---
90
+
91
+ ## Before you start
92
+
93
+ You need four things. If [our team runs the import for you](#have-kelviq-run-it-for-you), you only need the first and the third.
94
+
95
+ 1. **A Kelviq organization.** Create one at [app.kelviq.com](https://app.kelviq.com). The person who creates it is its owner.
96
+ 2. **A Kelviq Server API Key created by the organization owner.** Create it under **Settings → API keys** while signed in as the owner. A server key created by another team member, a Client API Key, or a dashboard session is refused with `403`. Sandbox and production each have their own keys.
97
+ 3. **A Lemon Squeezy API key.** Create one in your Lemon Squeezy dashboard under **Settings → API**.
98
+ 4. **Your Lemon Squeezy store id.** It is the number shown next to your store under **Settings → Stores**. One store is imported per run. A single Lemon Squeezy API key can reach several stores, so repeat the run with each store's id.
99
+
100
+ Both keys are secrets. Keep them in an env file or your shell, never in source control or a chat window.
101
+
102
+ ---
103
+
104
+ ## The path, start to finish
105
+
106
+ Kelviq keeps [sandbox and production](/guides/sandbox) separate. Each has its own data and its own keys, and nothing imported into one appears in the other. A dry run previews only the environment it ran in. The import goes into sandbox unless you choose production, so rehearse the whole move in sandbox, then repeat it in production.
107
+
108
+ ### In sandbox
109
+
110
+ 1. [Do a dry run](#run-the-import). Nothing is saved.
111
+ 2. [Read the report](#read-the-report) that is emailed to you.
112
+ 3. Run the real import. It publishes your plans and switches on your discount codes.
113
+ 4. [Review your plans and discount codes](#1-review-your-plans-and-discount-codes).
114
+ 5. [Add Kelviq to your app](#2-add-the-kelviq-equivalent-of-each-lemon-squeezy-call) with sandbox keys.
115
+ 6. [Test payments](#4-test-before-you-go-live) end to end.
116
+
117
+ ### In production
118
+
119
+ 1. Complete the [business review](/getstarted/review-process).
120
+ 2. Store a production key with `kelviq login --prod`.
121
+ 3. Do a dry run with `--prod` and read its report.
122
+ 4. Run the real import with `--prod`. Your plans are live as soon as it finishes.
123
+ 5. Review your plans and discount codes.
124
+ 6. Register your webhook endpoint with `--prod`.
125
+ 7. Switch your app to production keys. See [Prepare for production](/guides/sandbox#prepare-for-production).
126
+
127
+ Sales keep arriving on Lemon Squeezy while you switch. [Run the import again](#5-run-the-import-again-to-catch-up) to bring them in.
128
+
129
+ ---
130
+
131
+ ## Run the import
132
+
133
+ Start with a dry run. It goes through the whole import, saves nothing, and emails you a report of what a real run would do. The examples below import into sandbox.
134
+
135
+ Install the [Kelviq CLI](/cli/overview) and store your Kelviq key with `kelviq login`. To import into production, store a production key as well with `kelviq login --prod`.
136
+
137
+ The command needs your Lemon Squeezy API key. Give it either way:
138
+
139
+ * **From an env file.** The command reads `LEMONSQUEEZY_API_KEY` from `.env.local` or `.env` in the folder you run it from. Many apps already have it there.
140
+ * **At the prompt.** Run the command without the variable set and paste the key when asked. The input is masked.
141
+
142
+ Kelviq uses the key for this import only. It is never returned in a response or included in the report email.
143
+
144
+ Preview the import:
145
+
146
+ ```bash
147
+ kelviq import lemon-squeezy --store 12345 --dry-run
148
+ ```
149
+
150
+ When the report looks right, run it for real. The command shows what it is about to do and asks before it starts:
151
+
152
+ ```bash
153
+ kelviq import lemon-squeezy --store 12345
154
+ ```
155
+
156
+ Add `--prod` to either command to import into production. The Lemon Squeezy key is never taken as a flag and never printed. See the [command reference](/cli/commands#kelviq-import) for every option.
157
+
158
+ With the [Agent Toolkit](/guides/agent-toolkit) or the [MCP server](/guides/mcp-server) installed, set `LEMONSQUEEZY_API_KEY` in the same place as `KELVIQ_SERVER_API_KEY`:
159
+
160
+ * your shell profile, if your client reads keys from the shell
161
+ * the `env` block of the server entry in your MCP client's config, otherwise
162
+
163
+ Restart the client so the server picks up the key. Then ask your agent:
164
+
165
+ > *Do a dry run of importing my Lemon Squeezy store 12345 into Kelviq.*
166
+
167
+ The agent calls the `import_start` tool. The server reads the Lemon Squeezy key from its environment, so the key never appears in the conversation. Imports go to sandbox unless the server runs with `KELVIQ_ENV=production` and a production key. The tool's result names the environment and reminds the assistant that there is nothing to poll.
168
+
169
+ Once you have read the report, tell the agent to run the real import. With the toolkit's `migrate-to-kelviq` skill, the agent can also find the Lemon Squeezy calls in your codebase and add their Kelviq equivalents.
170
+
171
+ Call [Start a Lemon Squeezy import](/api-reference/imports/start-a-lemon-squeezy-import) from a backend or your terminal:
172
+
173
+ ```bash
174
+ curl -X POST "https://sandboxapi.kelviq.com/api/v1/integrations/lemon-squeezy/migrate/" \
175
+ -H "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
176
+ -H "Content-Type: application/json" \
177
+ -d '{"apiKey": "'"$LEMONSQUEEZY_API_KEY"'", "storeId": "12345", "dryRun": true}'
178
+ ```
179
+
180
+ A `202` response means the import is queued:
181
+
182
+ ```json
183
+ {
184
+ "status": "queued",
185
+ "taskId": "6f1c2f0e-8d3a-4a57-9b1e-2c1d5e7a9f10",
186
+ "storeName": "Acme Apps",
187
+ "steps": ["store", "products", "customers", "files", "orders", "renewals", "discounts", "licenses"],
188
+ "dryRun": true,
189
+ "reportEmail": "owner@example.com",
190
+ ...
191
+ }
192
+ ```
193
+
194
+ This request imports into sandbox, so it needs a sandbox key. To import into production, use `https://api.kelviq.com/api/v1` with a production key.
195
+
196
+ The import runs in the background and can take from a few seconds to more than an hour for a large store. There is no progress to check; the report email tells you when it is done.
197
+
198
+ ### Choose what to import
199
+
200
+ | Option | CLI flag | API field | Effect |
201
+ | --- | --- | --- | --- |
202
+ | Preview only | `--dry-run` | `dryRun` | Saves nothing and emails the report. |
203
+ | Pick steps | `--only`, `--skip` | `only`, `skip` | Run some steps, or leave some out. |
204
+ | Pick sales | `--orders` | `orderType` | All sales, one-time purchases only, or subscriptions only. |
205
+ | Keep plans as drafts | `--no-publish-plans` | `publishPlan: false` | Plans arrive as drafts for you to review and publish. Without it, each plan is published and can be sold straight away. |
206
+ | Keep discount codes off | `--no-publish-discounts` | `publishDiscount: false` | Codes arrive switched off. Without it, they work at checkout straight away. |
207
+ | Send the report elsewhere | `--report-email` | `reportEmail` | Defaults to the organization owner. |
208
+
209
+ ---
210
+
211
+ ## Have Kelviq run it for you
212
+
213
+ If you would rather not run anything yourself, our team does the import with you.
214
+
215
+ 1. **Create your Kelviq organization** at [app.kelviq.com](https://app.kelviq.com).
216
+ 2. **Create a Lemon Squeezy API key just for the move.** In your Lemon Squeezy dashboard, go to **Settings → API** and create a new key. Do not reuse the key your app runs on.
217
+ 3. **Share the key and your store id** with us at [hi@kelviq.com](mailto:hi@kelviq.com), from the email address on your Kelviq account.
218
+ 4. **We do the rest.** We do a dry run and send you the report. Once you approve it, we run the import, then check your plans, discount codes and license keys against your Lemon Squeezy store with you.
219
+ 5. **Delete the key** in Lemon Squeezy as soon as we confirm the import is finished, so it only lives as long as the move does.
220
+
221
+ Adding Kelviq checkout and webhooks to your app is still a change in your code. We help you through [those steps](#2-add-the-kelviq-equivalent-of-each-lemon-squeezy-call) too.
222
+
223
+ ---
224
+
225
+ ## Read the report
226
+
227
+ One email arrives when the import ends, whether it succeeded or stopped.
228
+
229
+ | Subject | Meaning |
230
+ | --- | --- |
231
+ | Lemon Squeezy import finished | Everything was imported. |
232
+ | Lemon Squeezy import finished with failures | The import completed, but some records could not be imported. They are listed, and retried the next time you run it. |
233
+ | Lemon Squeezy import failed | The import stopped part-way. The email names the step and the error. Everything imported before that point is kept. |
234
+
235
+ A dry run adds "(dry run, nothing saved)" to the subject.
236
+
237
+ The report contains:
238
+
239
+ * the store and the organization it went into
240
+ * a count for each record type, for example "Orders: 1,204 created, 3 skipped"
241
+ * the totals charged, tax and refunds from Lemon Squeezy, to compare with Kelviq's gross volume
242
+ * up to 50 warnings for anything that was skipped or imported differently
243
+ * the start time, the duration and the steps that ran
244
+
245
+ ---
246
+
247
+ ## After the import
248
+
249
+ ### 1. Review your plans and discount codes
250
+
251
+ The import publishes each plan, so it can be bought as soon as your app points at it, and your discount codes work at checkout. Open **Product Catalog → Products** in the dashboard and check each plan's price and settings against its variant in Lemon Squeezy. `kelviq status` lists every plan with its price and entitlement counts.
252
+
253
+ Then read the report's warnings. Two cases need you:
254
+
255
+ * **A plan that could not be published** stays a draft and is named in the report. Publish it in the dashboard.
256
+ * **A discount code limited to plans that are not published** stays switched off. Publish those plans, then run the import again to switch the code on.
257
+
258
+ To review everything before it can be bought, import with `--no-publish-plans` and `--no-publish-discounts` (`publishPlan: false` and `publishDiscount: false` in the API). When you are ready, run the import again without them: it publishes the plans it left as drafts and switches on the codes.
259
+
260
+ ### 2. Add the Kelviq equivalent of each Lemon Squeezy call
261
+
262
+ Existing subscribers still use the Lemon Squeezy calls in your app, so add the Kelviq ones beside them.
263
+
264
+ | In Lemon Squeezy | In Kelviq |
265
+ | --- | --- |
266
+ | Store | Organization |
267
+ | Product | [Product](/product-catalog/products) |
268
+ | Variant | [Plan](/product-catalog/plans) |
269
+ | Checkout link | A [checkout session](/backend-integration/node-sdk#checkout) created with `client.checkout.createSession`, or a [static checkout URL](/checkout/static-checkout-url) |
270
+ | Webhook with an `X-Signature` header | A [Kelviq webhook](/guides/webhooks), verified with `validateEvent` ([Node](/backend-integration/node-sdk#webhooks)) or `validate_event` ([Python](/backend-integration/python-sdk#webhooks)) |
271
+ | License API (`activate`, `validate`, `deactivate`) | From your backend, `client.license.activate`, `client.license.validate` and `client.license.deactivate`. In an app you ship to customers, the [license endpoints](/product-catalog/license-keys#authentication) with a **Client API Key**, never a server key |
272
+ | Customer portal URL | A [portal session](/backend-integration/node-sdk#portal) from `client.portal.createSession`; append the returned `token` to `customerPortalUrl` to build the link you send the customer |
273
+ | Discount code | [Discount code](/product-catalog/discounts) |
274
+
275
+ Copies of your app that are already installed keep calling Lemon Squeezy's license API until your users update. Ship the license change well before March 31, 2027.
276
+
277
+ Creating a checkout and verifying a webhook look like this in Node. `body` is the raw request body, and `client` is your [Kelviq client](/backend-integration/node-sdk#configuring-the-client).
278
+
279
+ ```typescript Lemon Squeezy
280
+ import crypto from "node:crypto";
281
+ import { createCheckout } from "@lemonsqueezy/lemonsqueezy.js";
282
+
283
+ // Create a checkout
284
+ const { data } = await createCheckout(storeId, variantId, {
285
+ productOptions: { redirectUrl: "https://yourwebsite.com/checkout/success" },
286
+ });
287
+ const checkoutUrl = data?.data.attributes.url;
288
+
289
+ // Verify a webhook
290
+ const digest = crypto
291
+ .createHmac("sha256", process.env.LEMONSQUEEZY_WEBHOOK_SECRET!)
292
+ .update(body)
293
+ .digest("hex");
294
+ const signature = request.headers.get("X-Signature") ?? "";
295
+ const valid =
296
+ digest.length === signature.length &&
297
+ crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
298
+ ```
299
+
300
+ ```typescript Kelviq
301
+ import { CHARGE_PERIOD_CHOICES, validateEvent } from "@kelviq/node-sdk";
302
+
303
+ // Create a checkout
304
+ const response = await client.checkout.createSession({
305
+ planIdentifier: "plan-pro-monthly",
306
+ chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
307
+ successUrl: "https://yourwebsite.com/checkout/success",
308
+ customerId: "cust_789",
309
+ });
310
+ const checkoutUrl = response.checkoutUrl;
311
+
312
+ // Verify a webhook. validateEvent throws WebhookVerificationError if the signature is invalid
313
+ const event = validateEvent(
314
+ body,
315
+ Object.fromEntries(request.headers),
316
+ process.env.KELVIQ_WEBHOOK_SECRET!,
317
+ );
318
+ ```
319
+
320
+ Webhook events map as follows.
321
+
322
+ | Lemon Squeezy event | Kelviq event |
323
+ | --- | --- |
324
+ | `order_created` | `checkout.completed`, `order.created` |
325
+ | `order_refunded` | `order.refunded` |
326
+ | `subscription_created` | `subscription.created` |
327
+ | `subscription_updated` | `subscription.updated`, `subscription.plan_changed` |
328
+ | `subscription_cancelled` | `subscription.updated` (the end date is set while the period runs out) |
329
+ | `subscription_resumed` | `subscription.updated` (a scheduled cancellation was undone). Not Kelviq's `subscription.resumed`, which is for pauses |
330
+ | `subscription_expired` | `subscription.cancelled` |
331
+ | `subscription_paused`, `subscription_unpaused` | `subscription.paused`, `subscription.resumed` |
332
+ | `subscription_payment_success`, `subscription_payment_recovered` | `invoice.paid` |
333
+ | `subscription_payment_failed` | `invoice.payment_failed` |
334
+ | `subscription_payment_refunded` | `order.refunded`, `refund.created` |
335
+ | `license_key_created` | No separate event. The key is issued with the order (`order.created`) |
336
+
337
+ Register your endpoint and write its signing secret into your env file in one command. List every event your handler uses:
338
+
339
+ ```bash
340
+ kelviq webhook add https://app.example.com/api/kelviq/webhooks --events checkout.completed,order.refunded,subscription.created,subscription.updated,subscription.cancelled,invoice.paid,invoice.payment_failed --write-secret .env.local
341
+ ```
342
+
343
+ ### 3. Keep the Lemon Squeezy path running
344
+
345
+ Existing subscribers still renew on Lemon Squeezy. Keep your Lemon Squeezy webhook handler, its signing secret, and the Lemon Squeezy portal link those subscribers use. Record which platform each subscription bills on, so that portal and cancel actions go to the right one. Remove the Lemon Squeezy path only when no subscription is billing there any more.
346
+
347
+ ### 4. Test before you go live
348
+
349
+ Run a purchase end to end in sandbox with the cards in [Test payments](/guides/test-payments), and confirm your app grants access from the Kelviq webhook.
350
+
351
+ ### 5. Run the import again to catch up
352
+
353
+ Sales and refunds keep happening on Lemon Squeezy while you switch. Run the full import again; it only adds what is new, including license keys issued since. Records that were already imported are skipped, and refunds made since the last run are picked up.
354
+
355
+ If you imported with `--no-publish-plans` or `--no-publish-discounts` and want to keep reviewing, pass them again. Without them, the catch-up run publishes the plans and switches on the codes.
356
+
357
+ ```bash
358
+ kelviq import lemon-squeezy --store 12345
359
+ ```
360
+
361
+ If you sell no license keys, `--only orders,renewals` is quicker:
362
+
363
+ ```bash
364
+ kelviq import lemon-squeezy --store 12345 --only orders,renewals
365
+ ```
366
+
367
+ ---
368
+
369
+ ## Common questions
370
+
371
+ A `400` with `Lemon Squeezy rejected the API key or the store id.` or `Lemon Squeezy store 12345 was not found for this API key.` means the Lemon Squeezy key or the store id is wrong. Check both. To list the store ids your key can reach, run this in a shell where `LEMONSQUEEZY_API_KEY` is set:
372
+
373
+ ```bash
374
+ curl -s -H "Authorization: Bearer $LEMONSQUEEZY_API_KEY" -H "Accept: application/vnd.api+json" https://api.lemonsqueezy.com/v1/stores
375
+ ```
376
+
377
+ Only one import runs per organization at a time, and a second request is refused with `409`. Wait for the report from the first.
378
+
379
+ Large stores can take over an hour, so allow time first. No report is sent in two cases:
380
+
381
+ * You started a second import while one was running. Only the first one reports.
382
+ * The import could not start within 24 hours.
383
+
384
+ After 24 hours, run the import again. If that returns `409` and still no report arrives, contact [hi@kelviq.com](mailto:hi@kelviq.com) with the `taskId` from the response. Support can clear a run that stopped.
385
+
386
+ Codes work at checkout as soon as the import finishes, with two exceptions: a code limited to plans that are not published, and every code if you imported with `--no-publish-discounts`. The report names each code that is waiting on a plan. Publish the plans it is limited to, then run the import again; it switches on the codes that are still off.
387
+
388
+ Read the `detail` in the response.
389
+
390
+ | `detail` | What to do |
391
+ | --- | --- |
392
+ | `Use a server key created by the organization owner.` | Have the organization owner create the Server API Key, and use that one. |
393
+ | `Invalid Bearer Token` | The Kelviq key is wrong, or it belongs to the other environment. A sandbox key only works against sandbox, and a production key against production. |
394
+
395
+ Yes, imported sales are added to revenue analytics. Pass `--skip-analytics` (`skipAnalytics` in the API) to leave them out.
396
+
397
+ ---
398
+
399
+ ## Related
400
+
401
+ * [Start a Lemon Squeezy import](/api-reference/imports/start-a-lemon-squeezy-import) is the API reference for the import.
402
+ * [Kelviq CLI commands](/cli/commands#kelviq-import) lists every `kelviq import` option.
403
+ * [Agent Toolkit](/guides/agent-toolkit) covers the skill that helps an AI agent move your app's code.
404
+ * [Webhooks](/guides/webhooks) lists every Kelviq event and how to verify it.
405
+ * [Sandbox](/guides/sandbox) explains environments and keys.
@@ -82,7 +82,7 @@ See the [Node SDK](/backend-integration/node-sdk), [Python SDK](/backend-integra
82
82
 
83
83
  ## Test checkout
84
84
 
85
- Create a checkout in the sandbox and use Stripe test card details. Use any future expiration date and a valid test CVC.
85
+ Create a checkout in the sandbox and pay with a test card. Use any future expiration date and any CVC.
86
86
 
87
87
  | Card number | Result |
88
88
  | --- | --- |
@@ -90,13 +90,15 @@ Create a checkout in the sandbox and use Stripe test card details. Use any futur
90
90
  | `4000 0000 0000 0002` | Declined payment |
91
91
  | `4000 0025 0000 3155` | Payment requiring authentication |
92
92
 
93
+ For every other outcome, including specific decline reasons, disputes, refunds, wallets, SEPA Direct Debit and UPI, see [Test payments](/guides/test-payments).
94
+
93
95
  Do not enter a real card number in the sandbox.
94
96
 
95
97
  After payment, confirm that the test order, customer, subscription, and entitlements have the expected state in Sandbox mode.
96
98
 
97
99
  ## Test a subscription renewal
98
100
 
99
- Daily billing is not enabled by default. Any sandbox organization can request it by contacting [Kelviq support](mailto:hi@kelviq.com).
101
+ To test renewals faster, ask [Kelviq support](mailto:hi@kelviq.com) to turn on Daily billing for your sandbox.
100
102
 
101
103
  After Daily billing is enabled, use it to test a renewal without waiting for a monthly or yearly billing cycle.
102
104
 
@@ -120,9 +122,9 @@ If you create the checkout session through the API, set `chargePeriod` to `DAILY
120
122
 
121
123
  ## Can I test production with my own card?
122
124
 
123
- No. Do not place a live order using your own card just to test production credentials. Payment providers can treat a self-payment as suspicious and block the card, even when the amount is small. There is no safe minimum price for this test.
125
+ Test in Sandbox or with a 100% discount code. A payment provider can flag your card if you pay yourself, even for a small amount.
124
126
 
125
- Use one of these options instead:
127
+ Here's how:
126
128
 
127
129
  * Keep payment and renewal testing in Sandbox.
128
130
  * If you need to inspect the production checkout, [create a 100% discount code](/product-catalog/discounts) so no real payment is collected.
@@ -0,0 +1,43 @@
1
+ ---
2
+ title: "Set up with AI"
3
+ slug: "guides/set-up-with-ai"
4
+ section: "guides"
5
+ description: "Hand billing to your AI coding agent with a prompt generated from your Kelviq account"
6
+ ---
7
+ **Settings → Set up with AI** writes a prompt for your coding agent. Paste it into Claude Code, Codex, VS Code, Windsurf, Cursor, Lovable, Replit, Bolt, Emergent, or any agent that can edit files and run commands, and the agent integrates Kelviq into your app.
8
+
9
+ It asks before changing anything in Kelviq and never needs your keys in the chat. Start in sandbox: your agent builds and tests with test cards, and when everything works, one command copies your catalog to production.
10
+
11
+ <img src="/images/set-up-with-ai-integrate.webp" alt="The Set up with AI page" />
12
+
13
+ ## Two ways to start
14
+
15
+ **Integrate with my app** is for a catalog you have already built. The agent connects the plans you have published: it adds a checkout route, a billing portal route, feature checks, and a webhook route that verifies signatures. If your app has a public URL, it registers the webhook too.
16
+
17
+ **Set up everything** is for a new product. The agent reads your app and your requirements, proposes plans, prices, limits, license keys and discount codes, and shows you what it will create. Nothing is created in Kelviq until you approve. It then builds the integration the same way.
18
+
19
+ <img src="/images/set-up-with-ai-everything.webp" alt="The Set up everything path, with approval steps before anything is created" />
20
+
21
+ ## Steps
22
+
23
+ 1. **Add your keys to the project.** Click **Copy for your .env file** and paste the block into your project's `.env.local` or `.env`, or into your app builder's secrets. The agent reads the keys from the file. Don't paste them into the chat.
24
+ 2. **Describe what you want (optional).** Plain language is fine: "one plan at $9/month with license keys, up to 3 devices per key, no free plan". Or add a common request, such as a monthly and yearly toggle or an upgrade button in settings. The agent follows these on top of its defaults and asks if something conflicts.
25
+ 3. **Give the prompt to your agent.** Click **Copy prompt**, open your agent in your app's project, and paste it as the first message.
26
+
27
+ The agent checks your keys with the Kelviq CLI without printing them and builds the app. In sandbox, it ends with a test purchase you can try with a [test card](/guides/sandbox).
28
+
29
+ ## Sandbox or production
30
+
31
+ The page gives you keys and a prompt for the mode you're in. Start in sandbox, where your agent builds and tests with test cards. When everything works, run [`kelviq promote`](/cli/commands#kelviq-promote) to copy your catalog to production, then add the production keys to your hosting settings.
32
+
33
+ If you open the page in production, it offers **Switch to sandbox**. If you carry on in production, the prompt targets your live account: the agent confirms with you before creating anything and stops at the checkout page instead of paying.
34
+
35
+ Three things stay with you: [business verification](/getstarted/review-process) and payouts, production keys in your hosting settings, and a production webhook endpoint.
36
+
37
+ On Claude Code, install the [Kelviq plugin](/guides/agent-toolkit) for extra tools. The prompt picks them up automatically.
38
+
39
+ ## Related documentation
40
+
41
+ - [Agent Toolkit](/guides/agent-toolkit)
42
+ - [MCP server](/guides/mcp-server)
43
+ - [CLI overview](/cli/overview)
@@ -19,7 +19,7 @@ Integrate Kelviq subscription billing into your Next.js application using the Ap
19
19
  ## Step 1: Get Your API Keys
20
20
 
21
21
  1. Sign up at [app.kelviq.com](https://app.kelviq.com)
22
- 2. Navigate to **Settings → API Keys**
22
+ 2. Navigate to **Settings → API keys**
23
23
  3. Copy two keys:
24
24
  - **Server API Key** — For API routes (keep secret)
25
25
  - **Client API Key** — For React SDK (safe to expose)
@@ -62,25 +62,24 @@ export const KELVIQ_API_URL =
62
62
 
63
63
  ### In Kelviq Dashboard
64
64
 
65
- 1. Go to **Plans** section
66
- 2. Create each subscription tier with:
65
+ 1. Go to **Product catalog → Products**, open your product, and add a plan for each tier with:
67
66
  - **Plan Identifier**: `base`, `pro`, `enterprise` (code-friendly names)
68
67
  - **Price**: Monthly/yearly pricing
69
68
  - **Features**: List of included features
70
69
 
71
- ### Define Entitlements
70
+ ### Add features & limits
72
71
 
73
- For each plan, configure entitlements (feature access):
72
+ For each plan, add features & limits:
74
73
 
75
74
  | Type | Description | Example |
76
75
  |------|-------------|---------|
77
- | **Boolean (FLAG)** | Feature is on/off | `export-data` |
78
- | **Metered (METER)** | Feature has usage limits | `max-projects: 10` |
79
- | **Config (CUSTOMIZABLE)** | Feature has configurable value | `team-size: 5` |
76
+ | **Boolean (`BOOLEAN`)** | Feature is on/off | `export-data` |
77
+ | **Meter feature (`METER`)** | Feature has usage limits | `max-projects: 10` |
78
+ | **Customizable (`CUSTOMIZABLE`)** | Feature has configurable value | `team-size: 5` |
80
79
 
81
80
  **Example Plan Structure:**
82
81
 
83
- | Feature | Base ($9/mo) | Pro ($49/mo) | Enterprise ($199/mo) |
82
+ | Feature | Base (\$9/mo) | Pro (\$49/mo) | Enterprise (\$199/mo) |
84
83
  |---------|--------------|--------------|----------------------|
85
84
  | max-projects | 10 | 100 | Unlimited |
86
85
  | export-data | No | Yes | Yes |
@@ -422,7 +421,7 @@ export function MyFeature() {
422
421
  disabled={maxProjects !== null && currentProjects >= maxProjects}
423
422
  onClick={createProject}
424
423
  >
425
- {remainingProjects > 0 ? "Create Project" : "Limit Reached"}
424
+ {remainingProjects === null || remainingProjects > 0 ? "Create Project" : "Limit Reached"}
426
425
  </button>
427
426
  </div>
428
427
 
@@ -535,4 +534,4 @@ function DashboardFeatures() {
535
534
  Have questions or need implementation support?
536
535
 
537
536
  - Email us at **hi@kelviq.com**
538
- - [Book a demo](https://tidycal.com/neravath/15-minute-meeting)
537
+ - [Book a demo](https://cal.com/alok-vats-fkpnc9/30min)
@@ -312,4 +312,4 @@ Use your **Client API Key** for this endpoint, not your Server API Key.
312
312
  Have questions or need implementation support?
313
313
 
314
314
  - Email us at **hi@kelviq.com**
315
- - [Book a demo](https://tidycal.com/neravath/15-minute-meeting)
315
+ - [Book a demo](https://cal.com/alok-vats-fkpnc9/30min)