@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,119 @@
1
+ ---
2
+ title: "Payment methods"
3
+ slug: "checkout/payment-methods"
4
+ section: "checkout"
5
+ description: "Cards, Apple Pay, Google Pay, UPI, PayPal, Klarna, iDEAL, SEPA Direct Debit, Pix, and the other ways customers can pay at Kelviq checkout"
6
+ ---
7
+ Kelviq checkout accepts cards, wallets, bank payments, buy now pay later, and local payment methods from around the world. You don't need to turn anything on or sign up with each provider. Kelviq is the merchant of record, so we handle the payment provider agreements, currency conversion, and payouts to you.
8
+
9
+ ## Which methods a customer sees
10
+
11
+ Checkout shows the methods that fit each purchase, based on:
12
+
13
+ * **The customer's country.** A buyer in the Netherlands sees iDEAL, a buyer in India sees UPI, a buyer in Brazil sees Pix.
14
+ * **The checkout currency.** Most local methods only work in their own currency. UPI needs INR, Pix needs BRL, iDEAL needs EUR. Set local prices with [location-based pricing](/product-catalog/location-based-pricing) so these methods can appear.
15
+ * **One-time or recurring.** Some methods can be charged again automatically for subscription renewals. Others can only be used for one-time payments, so checkout hides them for subscriptions.
16
+
17
+ Cards, Apple Pay, and Google Pay work almost everywhere and for both one-time payments and subscriptions.
18
+
19
+ ## Cards
20
+
21
+ | Method | Where | Subscriptions |
22
+ | --- | --- | --- |
23
+ | <img src="/images/payment-methods/visa.svg" alt="" className="pm-logo" noZoom />Visa | Worldwide | Yes |
24
+ | <img src="/images/payment-methods/mastercard.svg" alt="" className="pm-logo" noZoom />Mastercard | Worldwide | Yes |
25
+ | <img src="/images/payment-methods/amex.svg" alt="" className="pm-logo" noZoom />American Express | Worldwide | Yes |
26
+ | <img src="/images/payment-methods/discover.svg" alt="" className="pm-logo" noZoom />Discover | Worldwide | Yes |
27
+ | <img src="/images/payment-methods/diners-club.svg" alt="" className="pm-logo" noZoom />Diners Club | Worldwide | Yes |
28
+ | <img src="/images/payment-methods/jcb.svg" alt="" className="pm-logo" noZoom />JCB | Worldwide | Yes |
29
+ | <img src="/images/payment-methods/unionpay.svg" alt="" className="pm-logo" noZoom />UnionPay | Worldwide | Yes |
30
+ | <img src="/images/payment-methods/cartes-bancaires.svg" alt="" className="pm-logo" noZoom />Cartes Bancaires | France | Yes |
31
+ | <img src="/images/payment-methods/eftpos.svg" alt="" className="pm-logo" noZoom />eftpos | Australia | Yes |
32
+ | <img src="/images/payment-methods/card.svg" alt="" className="pm-logo" noZoom />Korean local cards | South Korea | Yes |
33
+
34
+ ## Wallets
35
+
36
+ | Method | Where | Subscriptions |
37
+ | --- | --- | --- |
38
+ | <img src="/images/payment-methods/apple-pay.svg" alt="" className="pm-logo" noZoom />Apple Pay | Wherever Apple Pay is available | Yes |
39
+ | <img src="/images/payment-methods/google-pay.svg" alt="" className="pm-logo" noZoom />Google Pay | Wherever Google Pay is available | Yes |
40
+ | <img src="/images/payment-methods/link.svg" alt="" className="pm-logo" noZoom />Link | Most countries | Yes |
41
+ | <img src="/images/payment-methods/paypal.svg" alt="" className="pm-logo" noZoom />PayPal | Worldwide | Yes |
42
+ | <img src="/images/payment-methods/amazon-pay.svg" alt="" className="pm-logo" noZoom />Amazon Pay | Worldwide (USD) | Yes |
43
+ | <img src="/images/payment-methods/revolut-pay.svg" alt="" className="pm-logo" noZoom />Revolut Pay | UK and EU | Yes |
44
+ | <img src="/images/payment-methods/cash-app-pay.svg" alt="" className="pm-logo" noZoom />Cash App Pay | United States | Yes |
45
+ | <img src="/images/payment-methods/kakao-pay.svg" alt="" className="pm-logo" noZoom />Kakao Pay | South Korea | Yes |
46
+ | <img src="/images/payment-methods/naver-pay.svg" alt="" className="pm-logo" noZoom />Naver Pay | South Korea | Yes |
47
+ | <img src="/images/payment-methods/alipay.svg" alt="" className="pm-logo" noZoom />Alipay | Customers in China | One-time only |
48
+ | <img src="/images/payment-methods/wechat-pay.svg" alt="" className="pm-logo" noZoom />WeChat Pay | Customers in China | One-time only |
49
+ | <img src="/images/payment-methods/mobilepay.svg" alt="" className="pm-logo" noZoom />MobilePay | Denmark, Finland | One-time only |
50
+ | <img src="/images/payment-methods/mb-way.svg" alt="" className="pm-logo" noZoom />MB WAY | Portugal | One-time only |
51
+ | <img src="/images/payment-methods/grabpay.svg" alt="" className="pm-logo" noZoom />GrabPay | Malaysia, Singapore | One-time only |
52
+ | <img src="/images/payment-methods/paypay.svg" alt="" className="pm-logo" noZoom />PayPay | Japan | One-time only |
53
+
54
+ ## Bank redirects
55
+
56
+ The customer is sent to their bank or banking app to approve the payment, then back to checkout.
57
+
58
+ | Method | Where | Currency | Subscriptions |
59
+ | --- | --- | --- | --- |
60
+ | <img src="/images/payment-methods/ideal-wero.svg" alt="" className="pm-logo" noZoom />iDEAL (Wero) | Netherlands | EUR | Yes, renewals are charged by SEPA Direct Debit |
61
+ | <img src="/images/payment-methods/bancontact.svg" alt="" className="pm-logo" noZoom />Bancontact | Belgium | EUR | Yes, renewals are charged by SEPA Direct Debit |
62
+ | <img src="/images/payment-methods/blik.svg" alt="" className="pm-logo" noZoom />BLIK | Poland | PLN | Yes |
63
+ | <img src="/images/payment-methods/twint.svg" alt="" className="pm-logo" noZoom />TWINT | Switzerland | CHF | Yes |
64
+ | <img src="/images/payment-methods/eps.svg" alt="" className="pm-logo" noZoom />EPS | Austria | EUR | One-time only |
65
+ | <img src="/images/payment-methods/przelewy24.svg" alt="" className="pm-logo" noZoom />Przelewy24 | Poland | EUR, PLN | One-time only |
66
+ | <img src="/images/payment-methods/fpx.svg" alt="" className="pm-logo" noZoom />FPX | Malaysia | MYR | One-time only |
67
+
68
+ ## Bank debits
69
+
70
+ The customer enters their bank account details once and is debited directly. Good for B2B customers and high-value subscriptions.
71
+
72
+ | Method | Where | Currency | Subscriptions |
73
+ | --- | --- | --- | --- |
74
+ | <img src="/images/payment-methods/sepa-debit.svg" alt="" className="pm-logo" noZoom />SEPA Direct Debit | Euro area and SEPA countries | EUR | Yes |
75
+ | <img src="/images/payment-methods/ach-debit.svg" alt="" className="pm-logo" noZoom />ACH Direct Debit | United States | USD | Yes |
76
+ | <img src="/images/payment-methods/bacs-debit.svg" alt="" className="pm-logo" noZoom />Bacs Direct Debit | United Kingdom | GBP | Yes |
77
+ | <img src="/images/payment-methods/becs-debit.svg" alt="" className="pm-logo" noZoom />BECS Direct Debit | Australia, New Zealand | AUD, NZD | Yes |
78
+
79
+ ## Buy now, pay later
80
+
81
+ The customer splits the payment into instalments. The provider pays the full amount at checkout.
82
+
83
+ | Method | Where | Subscriptions |
84
+ | --- | --- | --- |
85
+ | <img src="/images/payment-methods/klarna.svg" alt="" className="pm-logo" noZoom />Klarna | US, Canada, UK, most of Europe, Australia, New Zealand | Yes, in some countries |
86
+ | <img src="/images/payment-methods/afterpay.svg" alt="" className="pm-logo" noZoom />Afterpay / Clearpay | US, Canada, UK, Australia, New Zealand | One-time only |
87
+ | <img src="/images/payment-methods/affirm.svg" alt="" className="pm-logo" noZoom />Affirm | US, Canada | One-time only |
88
+ | <img src="/images/payment-methods/zip.svg" alt="" className="pm-logo" noZoom />Zip | Australia | One-time only |
89
+
90
+ ## Real-time payments
91
+
92
+ | Method | Where | Currency | Subscriptions |
93
+ | --- | --- | --- | --- |
94
+ | <img src="/images/payment-methods/upi.svg" alt="" className="pm-logo" noZoom />[UPI](/checkout/payment-methods/upi) | India | INR | Yes, with UPI AutoPay |
95
+ | <img src="/images/payment-methods/pix.svg" alt="" className="pm-logo" noZoom />Pix | Brazil | BRL | Yes, with Pix Automático |
96
+ | <img src="/images/payment-methods/paynow.svg" alt="" className="pm-logo" noZoom />PayNow | Singapore | SGD | One-time only |
97
+ | <img src="/images/payment-methods/promptpay.svg" alt="" className="pm-logo" noZoom />PromptPay | Thailand | THB | One-time only |
98
+ | <img src="/images/payment-methods/pay-by-bank.svg" alt="" className="pm-logo" noZoom />Pay by Bank | United Kingdom | GBP | One-time only |
99
+
100
+ ## Vouchers
101
+
102
+ The customer gets a voucher and pays it in cash or online at a store, bank, or ATM. The order completes when the payment arrives, which can take a day or more.
103
+
104
+ | Method | Where | Currency | Subscriptions |
105
+ | --- | --- | --- | --- |
106
+ | <img src="/images/payment-methods/boleto.svg" alt="" className="pm-logo" noZoom />Boleto | Brazil | BRL | Yes, a new voucher for each renewal |
107
+ | <img src="/images/payment-methods/oxxo.svg" alt="" className="pm-logo" noZoom />OXXO | Mexico | MXN | One-time only |
108
+ | <img src="/images/payment-methods/konbini.svg" alt="" className="pm-logo" noZoom />Konbini | Japan | JPY | One-time only |
109
+ | <img src="/images/payment-methods/multibanco.svg" alt="" className="pm-logo" noZoom />Multibanco | Portugal | EUR | One-time only |
110
+
111
+ ## UPI
112
+
113
+ UPI limits, UPI AutoPay subscriptions and refunds are on the [UPI page](/checkout/payment-methods/upi).
114
+
115
+ ## Related
116
+
117
+ * [Checkout examples](/checkout/checkout-examples) shows checkout for each pricing model.
118
+ * [Location-based pricing](/product-catalog/location-based-pricing) sets prices in local currencies.
119
+ * [Managing payment methods](/customer-portal/managing-payment-methods) explains how customers update the method used for renewals.
@@ -12,7 +12,7 @@ Static links work well on pricing pages, in emails, and behind a purchase button
12
12
 
13
13
  1. Open **Product Catalog → Products**.
14
14
  2. Select a published product.
15
- 3. Click **Get link** or **Copy checkout link**.
15
+ 3. Click **Get Link**, then copy the link.
16
16
  4. Choose the plans and default billing period.
17
17
  5. Copy the generated URL.
18
18
 
@@ -28,7 +28,7 @@ Sandbox links include `/sandbox/`:
28
28
  https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/
29
29
  ```
30
30
 
31
- The product UUID is part of the copied link. Do not replace it with the old product identifier.
31
+ The product UUID is part of the copied link.
32
32
 
33
33
  ## Available query parameters
34
34
 
@@ -195,6 +195,7 @@ Keep sandbox products, customers, discounts, and API credentials together. A liv
195
195
 
196
196
  ## Related documentation
197
197
 
198
+ - [Checkout examples](/checkout/checkout-examples)
198
199
  - [Checkout configuration](/checkout/checkout-configuration)
199
200
  - [Apply a discount code at checkout](/checkout/apply-a-discount-code)
200
201
  - [Add metadata to checkout](/checkout/checkout-metadata)
@@ -6,7 +6,7 @@ description: "Every Kelviq CLI command, flag by flag."
6
6
  ---
7
7
  All commands support `--help`. The CLI targets your **sandbox** environment unless you pass `--prod` — see [Environments & authentication](/cli/environments).
8
8
 
9
- Every command reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory before it runs, so a project's env file works without exporting anything. A variable already set in your shell always wins. Two global flags control this:
9
+ Every command reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory before it runs, so a project's env file works without exporting anything. [`kelviq import`](#kelviq-import) also reads its source's own variables from those files. A variable already set in your shell always wins. Two global flags control this:
10
10
 
11
11
  | Flag | Description |
12
12
  |---|---|
@@ -37,7 +37,7 @@ kelviq init --force
37
37
 
38
38
  Each template is a complete catalog that `kelviq push` accepts as written, using the typed builders from `@kelviq/cli/config` — see the [format reference](/cli/kelviq-config):
39
39
 
40
- - **`saas`** — a product with a free plan and a Pro plan billed monthly or yearly, gating a boolean feature and a configurable limit.
40
+ - **`saas`** — a product with a free plan and a Pro plan billed monthly or yearly, gating a Boolean feature and a Customizable limit.
41
41
  - **`usage`** — a `METER` feature with the details the API requires, a free plan with a hard monthly allowance, and a Pro plan with an included quantity plus a tiered pay-as-you-go overage price.
42
42
  - **`license`** — a Pro plan whose orders issue license keys valid on up to three devices.
43
43
 
@@ -64,7 +64,7 @@ What it does:
64
64
 
65
65
  Paste a **Server API Key**, not a Client API Key. Server keys have full API access — treat the config file like any other credential store, and never commit it anywhere.
66
66
 
67
- Kelviq has no key-introspection endpoint yet, so `login` cannot verify the key is valid or show which organization it belongs to — the first `pull` is where a bad key surfaces.
67
+ `login` does not check the key. Run `kelviq env --check` afterwards to confirm the API accepts it. Kelviq has no key-introspection endpoint yet, so the CLI can't show which organization the key belongs to.
68
68
 
69
69
  For CI and other non-interactive contexts, skip `login` entirely and set an environment variable instead — see [Environments & authentication](/cli/environments#environment-variables).
70
70
 
@@ -210,7 +210,7 @@ The API rejects a `METER` feature created without `featureDetails` (`featureSubT
210
210
 
211
211
  ### Features can't be updated — by design
212
212
 
213
- The Kelviq API deliberately treats feature attributes as immutable; renaming a feature is a dashboard operation. If a feature in your config differs from its remote counterpart, push stops **before writing anything** and lists the drifted fields — fix the feature in the [dashboard](https://app.kelviq.com), run `kelviq pull`, and push again.
213
+ The Kelviq API deliberately treats feature attributes as immutable; renaming a feature is a dashboard operation. If a feature in your config differs from its remote counterpart, push stops **before writing anything** and lists the drifted fields. A feature's identifier and type can't change: to change them, create a new feature, then run `kelviq pull` and push again. Edit the name in the [dashboard](https://app.kelviq.com).
214
214
 
215
215
  ### Publishing
216
216
 
@@ -358,3 +358,56 @@ Discount codes need a Merchant of Record organization.
358
358
  ### kelviq discount list
359
359
 
360
360
  Lists codes with amount, duration and state. `--search <text>` filters by name or code; `--prod` and `--json` as above.
361
+
362
+ ---
363
+
364
+ ## kelviq import
365
+
366
+ Brings an existing store from another platform into your Kelviq organization. Lemon Squeezy is supported. The import runs on Kelviq's servers: the command starts it and returns, and a report is emailed when it finishes. There is no progress to poll.
367
+
368
+ ```shell
369
+ kelviq import # list the available sources
370
+ kelviq import lemon-squeezy --store 12345 --dry-run # preview: saves nothing, emails a report
371
+ kelviq import lemon-squeezy --store 12345 # confirm, then start the import
372
+ kelviq import lemon-squeezy --store 12345 # run it again to catch up: only what is new is added
373
+ kelviq import lemon-squeezy --store 12345 --only orders,renewals # quicker catch-up for stores without license keys
374
+ ```
375
+
376
+ These flags apply to every source:
377
+
378
+ | Flag | Description |
379
+ |---|---|
380
+ | `--dry-run` | Run the whole import and save nothing. The report shows what a real run would do. Needs no confirmation and no `--yes`. |
381
+ | `--only <steps>` | Comma-separated steps to run. Defaults to every step. |
382
+ | `--skip <steps>` | Comma-separated steps to leave out. |
383
+ | `--no-publish-plans` | Import plans as drafts to review and publish yourself. Without it, each imported plan is published and can be sold straight away. |
384
+ | `--no-publish-discounts` | Leave imported discount codes switched off. Without it, they work at checkout straight away. |
385
+ | `--report-email <address>` | Where the report is sent. Defaults to the organization owner. |
386
+ | `--prod` | Import into production instead of sandbox. |
387
+ | `--yes` | Skip the confirmation prompt. Required for a real run in a non-interactive session. |
388
+ | `--json` | Print one JSON document on stdout: `{ environment, source, import }` when the import is queued, or `{ error }` when it is not. The summary and prompts go to stderr. |
389
+
390
+ Before it sends anything, the command prints a summary on stderr: the environment, the source, the store, where the key came from, the steps, the order type, whether plans and discount codes are published, and the report address. A real run then asks before it starts; in a non-interactive session it refuses without `--yes`. Production is labelled `PRODUCTION (live data)` in the summary and in the prompt.
391
+
392
+ If the API host is not Kelviq's own, for example because an env file in the working directory sets `KELVIQ_BASE_URL`, the summary shows the host and the command asks for confirmation even for a dry run.
393
+
394
+ The command only reports that an import started when the API confirms it was queued. Pressing Ctrl-C at the key prompt cancels without starting anything.
395
+
396
+ The Kelviq key must be a Server API Key created by the organization **owner**; a key created by another team member is refused. Only one import runs per organization at a time.
397
+
398
+ Running an import again is safe: records already imported are skipped, new ones are added, and refunds made since are picked up. It also publishes plans an earlier run left as drafts and switches on discount codes that are still off, unless you pass `--no-publish-plans` or `--no-publish-discounts` again.
399
+
400
+ ### kelviq import lemon-squeezy
401
+
402
+ | Flag | Description |
403
+ |---|---|
404
+ | `--store <id>` | The Lemon Squeezy store to import, a number. Read from `LEMONSQUEEZY_STORE_ID` when omitted, and prompted for in an interactive terminal. One store per run. |
405
+ | `--orders <all\|one-time\|subscription>` | Which sales to import. Default `all`. License keys follow their orders. |
406
+ | `--overwrite-profile` | Overwrite the organization name and business profile fields that are already filled in. Without it, only blank fields are filled. |
407
+ | `--skip-analytics` | Don't add the imported sales to revenue analytics. |
408
+
409
+ The Lemon Squeezy API key is read from `LEMONSQUEEZY_API_KEY`, in your shell or in `.env.local` / `.env`. When it isn't set, an interactive terminal prompts for it with masked input. Anywhere else, the command stops and names the variable to set. There is no flag for the key, and it is never printed, including in `--json` output and error messages.
410
+
411
+ Steps, in the order they run: `store`, `products`, `customers`, `files`, `orders`, `renewals`, `discounts`, `licenses`. `orders` needs `products`, and `renewals` and `licenses` need `orders`; these may have run in an earlier import.
412
+
413
+ Subscriptions are imported as history. They keep renewing on Lemon Squeezy until it stops processing payments on March 31, 2027, and Kelviq does not charge them. See [Migrate from Lemon Squeezy](/guides/migrate-from-lemon-squeezy) for the full walkthrough.
@@ -131,7 +131,7 @@ Each entry grants a feature to the plan:
131
131
  |---|---|---|---|
132
132
  | `feature` | slug | yes | Identifier of the granted feature. |
133
133
  | `value` | boolean or number | no | The grant: `true`/`false` for `BOOLEAN` features, a number for limits. |
134
- | `hasUnlimitedUsage` | boolean | no | Grant unlimited usage instead of a numeric value. |
134
+ | `hasUnlimitedUsage` | boolean | no | Grant unlimited usage instead of a numeric value. Omit `value` when this is `true`; `kelviq pull` writes unlimited entitlements this way. |
135
135
  | `reset` | enum | no | Usage reset cadence: `NEVER`, `EVERY_DAY`, `EVERY_28_DAYS`, `EVERY_MONTH`, `EVERY_QUARTER`, `EVERY_YEAR`. |
136
136
  | `hardLimit` | boolean | no | Whether usage is blocked at the limit. |
137
137
  | `usageAlerts` | object | no | Alert configuration, passed through to the API. |
@@ -217,6 +217,7 @@ When you're happy, `kelviq push --publish` makes the changed plans live, and `ke
217
217
  | [`kelviq status`](/cli/commands#kelviq-status) | Show the live catalog: products, features, each plan's latest version with price and entitlement counts. |
218
218
  | [`kelviq webhook`](/cli/commands#kelviq-webhook) | Register the app's webhook endpoint and write its signing secret into an env file without printing it. |
219
219
  | [`kelviq discount`](/cli/commands#kelviq-discount) | Create and list discount codes, with the product given by identifier. |
220
+ | [`kelviq import`](/cli/commands#kelviq-import) | Import an existing store from another platform: preview with a dry run, then start it. Lemon Squeezy is supported. |
220
221
 
221
222
  See the full [command reference](/cli/commands) for every flag, and the [`kelviq.config.ts` reference](/cli/kelviq-config) for the file format.
222
223
 
@@ -18,7 +18,7 @@ If that payment method fails because it has expired, has insufficient funds, or
18
18
 
19
19
  ## How customers pay a failed card invoice
20
20
 
21
- If an automatic card payment fails, your customer gets an email with a link to pay the invoice. They can also open **Settings > Billing** in the Customer Portal to add or update a payment method.
21
+ If an automatic card payment fails, your customer gets an email with a link to pay the invoice. They can also open **Billing settings** in the customer portal sidebar to add or update a payment method.
22
22
 
23
23
  Paying an invoice manually does not turn off automatic payments. The customer's payment authorization remains active for future renewals.
24
24
 
@@ -39,7 +39,7 @@ The new payment method appears under **Saved payment methods**.
39
39
 
40
40
  The default payment method is used as a fallback if the payment method attached to a subscription fails.
41
41
 
42
- 1. The customer opens **Settings > Billing**.
42
+ 1. The customer opens **Billing settings** in the customer portal sidebar.
43
43
  2. They find the payment method they want to use as the default.
44
44
  3. They click the star icon next to it.
45
45
 
@@ -47,8 +47,8 @@ The portal adds a **Default** badge to the selected payment method.
47
47
 
48
48
  ### Delete a payment method
49
49
 
50
- Customers cannot delete their current default payment method. They must set another payment method as the default first.
50
+ To delete the default payment method, a customer first sets another one as default.
51
51
 
52
- 1. The customer opens **Settings > Billing**.
52
+ 1. The customer opens **Billing settings** in the customer portal sidebar.
53
53
  2. They find the payment method they want to remove.
54
54
  3. They click the trash icon next to it.
@@ -27,13 +27,13 @@ The portal uses passwordless, secure access.
27
27
  We send a one-time access code to their email. They enter this code to log in. No passwords to remember.
28
28
 
29
29
 
30
- <img height="200" src="/images/portal-login.png" />
30
+ <img src="/images/portal-login.webp" />
31
31
 
32
32
  ## My orders
33
33
 
34
34
  This is the home screen. It lists everything the customer owns. They can click on a specific product to see details.
35
35
 
36
- <img height="200" src="/images/orders-list.png" />
36
+ <img src="/images/orders-list.webp" />
37
37
 
38
38
  ### Product details
39
39
  Inside a specific product, customers find their deliverables.
@@ -45,7 +45,7 @@ Inside a specific product, customers find their deliverables.
45
45
  * **License management**
46
46
  View license keys. If you enforce seat limits, customers can see active devices and revoke licenses to free up seats for new team members.
47
47
 
48
- <img height="200" src="/images/product-downloads.png" />
48
+ <img src="/images/product-downloads.webp" />
49
49
 
50
50
  ## Subscription management
51
51
 
@@ -54,11 +54,11 @@ Customers have control over their lifecycle without contacting you.
54
54
  * **Change plans**
55
55
  Upgrade to a higher tier or downgrade.
56
56
  * **Pause and cancel**
57
- Pause a subscription temporarily or stop it entirely.
57
+ Pause a subscription temporarily or stop it entirely. With [retention offers](/customer-portal/retention) on, customers see an offer before they cancel.
58
58
  * **Payment methods**
59
59
  Update credit card details or switch methods for future renewals.
60
60
 
61
- <img height="200" src="/images/update-payment-modal.png" />
61
+ <img src="/images/update-payment-modal.webp" />
62
62
 
63
63
  ## Billing settings
64
64
 
@@ -67,7 +67,7 @@ This section handles compliance and admin tasks.
67
67
  ### Invoices and receipts
68
68
  Customers can view their full payment history. They can download PDF invoices and receipts for their own accounting.
69
69
 
70
- <img height="200" src="/images/invoices-tab.png" />
70
+ <img src="/images/invoices-tab.webp" />
71
71
 
72
72
  ### Account details
73
73
  This is where they manage the legal side of the account.
@@ -78,4 +78,4 @@ This is where they manage the legal side of the account.
78
78
  * **Account transfer**
79
79
  Transfer ownership of the account and subscription to a different email address.
80
80
 
81
- <img height="200" src="/images/billing-settings.png" />
81
+ <img src="/images/billing-settings.webp" />
@@ -0,0 +1,109 @@
1
+ ---
2
+ title: "Retention offers"
3
+ slug: "customer-portal/retention"
4
+ section: "customer-portal"
5
+ description: "Ask customers why they're cancelling and make an offer to keep them"
6
+ ---
7
+ When a customer cancels a subscription in the [customer portal](/customer-portal/overview), Kelviq asks why, then shows the offer you picked for that reason: a discount, a pause, or a link to your support team. If the customer says no, they continue to cancel.
8
+
9
+ Set it up in **Settings → Retention** and turn on **Enable retention offer**.
10
+
11
+ ## Where customers see offers
12
+
13
+ | Where the customer cancels | What you do |
14
+ | --- | --- |
15
+ | **Customer portal** | Nothing. Offers show automatically. |
16
+ | **A Cancel button in your own app** | When the customer clicks it, call [Get retention offers](/api-reference/subscriptions/get-retention-offers) to show the reasons and offers, then [Accept a retention offer](/api-reference/subscriptions/accept-a-retention-offer) for the one they pick. |
17
+
18
+ Offers, reasons and rules are the same in both. You set them once in **Settings → Retention**.
19
+
20
+ ## What the customer sees
21
+
22
+
23
+
24
+
25
+
26
+ <img src="/images/retention/retention-reason.webp" alt="The cancellation dialog asking the customer to pick a reason" />
27
+
28
+
29
+
30
+
31
+
32
+
33
+ The offer depends on the reason. Here, **Not using it enough** leads to a pause.
34
+
35
+
36
+
37
+ <img src="/images/retention/retention-pause-offer.webp" alt="An offer to pause the subscription for 1, 3, or 6 months" />
38
+
39
+
40
+
41
+
42
+
43
+
44
+ A customer who declines the offer chooses when access ends: at the end of the billing period, immediately, or on a date they pick. If you've turned on written feedback, your question appears here too.
45
+
46
+
47
+
48
+ <img src="/images/retention/retention-confirm.webp" alt="The final cancellation step with end date options and a feedback question" />
49
+
50
+
51
+
52
+
53
+ ## Set up your offers
54
+
55
+ Set each offer up once. Then choose which reasons show it.
56
+
57
+ <img src="/images/retention/retention-offers.webp" alt="Retention settings with the Discount, Pause, and Support offers" />
58
+
59
+ | Offer | What you set | What happens if the customer accepts |
60
+ | --- | --- | --- |
61
+ | Discount | A percentage off and how many billing cycles it lasts | The plan stays the same and the next payments are discounted. After that, the price goes back to normal |
62
+ | Pause | Which lengths to offer: 1, 3, or 6 months | Billing and access stop for the period they choose, then resume. See [Pause a subscription](/product-catalog/subscriptions#pause-a-subscription) |
63
+ | Support | A link to a booking page, live chat, or your help site | They go to that link. Nothing changes on the subscription |
64
+
65
+ Use the eye icon next to an offer to preview it.
66
+
67
+ <img src="/images/retention/retention-discount-offer.webp" alt="A discount offer of 20% off the next 3 payments" />
68
+
69
+ ## Match offers to reasons
70
+
71
+ Under **Offers by cancellation reason**, pick an offer for each reason, or **No offer** to let the customer go straight to the final step.
72
+
73
+ <img src="/images/retention/retention-offers-by-reason.webp" alt="Offers by cancellation reason, with an offer chosen for each reason" />
74
+
75
+ | Reason | Example offer |
76
+ | --- | --- |
77
+ | Too expensive | Discount |
78
+ | Not using it enough | Pause |
79
+ | Missing features | Support |
80
+ | Switching to another product | No offer |
81
+ | Technical issues | Support |
82
+ | Poor support experience | Support |
83
+ | Business or project ended | No offer |
84
+ | Other | No offer |
85
+
86
+ Offer what fits the reason. A customer who isn't using the product won't stay for a discount, but might come back after a pause.
87
+
88
+ ## Ask for written feedback
89
+
90
+ Turn on **Written feedback** to ask one open question before the customer confirms, such as "What could we do better?". Answering is optional. The answer is saved as the cancellation comment on the subscription.
91
+
92
+ ## When an offer isn't available
93
+
94
+ An offer the customer can't use still appears, greyed out, with the reason. A customer sees an offer only once per subscription unless you change the repeat policy below, and offers aren't available on free or manually billed subscriptions.
95
+
96
+ A pause has to cover at least one full billing period, so yearly plans don't get a pause offer. Only an active subscription can be paused: not one on trial, past due, or already scheduled to cancel.
97
+
98
+ ## Advanced settings
99
+
100
+ | Setting | Options |
101
+ | --- | --- |
102
+ | Resume billing behavior | **Reset billing cycle** (default) charges a full period on the day the subscription resumes and makes that the new billing day. **Keep billing day** charges nothing on resume and waits for the original billing day. A customer who resumes inside a period they've already paid for is never charged again, whichever you choose |
103
+ | Offer repeat policy | **Once per subscription** (default), **After previous offer ends**, or **Unlimited**. Controls whether a customer who accepted an offer can accept it again on a later cancellation. A plan change doesn't reset this |
104
+
105
+ ## Related documentation
106
+
107
+ - [Customer portal](/customer-portal/overview)
108
+ - [Subscriptions](/product-catalog/subscriptions)
109
+ - [Discounts](/product-catalog/discounts)
@@ -0,0 +1,105 @@
1
+ ---
2
+ title: "Overview"
3
+ slug: "customers-management/overview"
4
+ section: "customers-management"
5
+ description: "View and manage customer details, subscriptions, and entitlements."
6
+ ---
7
+ Managing customers sits at the center of Kelviq. Each customer connects directly to their subscriptions, the plans behind them, and the features they own. You need to understand these relationships to handle the full customer lifecycle.
8
+
9
+ ## View customer list
10
+
11
+ Select **Customers** in the main navigation to see your list.
12
+
13
+ You can do a few things here.
14
+ * **Search** by name, email, or identifier.
15
+ * **Add a new customer** with **New customer** in the top right.
16
+ * **Manage a customer** by clicking their row to see details.
17
+
18
+ <img src="/images/customers-list.webp" />
19
+
20
+ ## Add a new customer
21
+
22
+ You can create records manually.
23
+
24
+
25
+
26
+ Click **+ New customer** in the top right of the list page.
27
+
28
+
29
+
30
+
31
+ You need to provide a few key pieces of info.
32
+ * **Customer name** is required. Use the person's full name or company name.
33
+ * **Identifier** is the unique ID the API uses. We auto-generate this based on the name, but you can edit it. Use the ID from your own database so the API and your app match.
34
+ * **Email address** is optional.
35
+
36
+
37
+
38
+
39
+ Click **Create** to finish.
40
+
41
+
42
+ <img src="/images/create-customer-modal.webp" />
43
+
44
+ More than one customer record can use the same email address, but every record must have a unique **Identifier**. The API calls this value `customerId`.
45
+
46
+ When recreating a test customer, you can reuse the email address, but you must provide a new Identifier. An Identifier cannot be reused after its customer is archived. If you receive a `customer already exists` error, check the Identifier first.
47
+
48
+ ## Manage existing customers
49
+
50
+ You can edit details or revoke access from the list view.
51
+
52
+ ### Edit a customer
53
+ Click the **three dots** on the right side of the customer row and select **Edit**.
54
+
55
+ <img src="/images/edit-customer.webp" />
56
+
57
+ You can update the **Customer name** and **Email address**. The Identifier is fixed after creation and cannot be changed.
58
+
59
+ ### Archive a customer
60
+ Archiving makes a customer inactive and revokes their access. Click the **three dots** and select **Archive**.
61
+
62
+ <img src="/images/archive-customer.webp" />
63
+
64
+ You will see a confirmation warning. Click **Confirm** to proceed.
65
+
66
+ Kelviq archives customers; it does not hard-delete them. The archived record keeps its Identifier, so that value cannot be reused. To create another customer with the same email address, use a new Identifier.
67
+
68
+ To archive a customer with an active subscription, cancel the subscription first.
69
+
70
+ ## Customer details
71
+
72
+ Click on any customer row to open their full profile.
73
+
74
+ This page holds the source of truth for that user. You can see their unique Billing ID and timestamps for when they joined or were last updated.
75
+
76
+ <img src="/images/customer-details.webp" />
77
+
78
+ ### Subscriptions
79
+
80
+ This section lists active and past plans. It shows the status, such as Active or Canceled, and the relevant dates. For a canceled subscription, the date it was canceled appears alongside the status.
81
+
82
+ ### Files, links, and license keys
83
+
84
+ The customer detail page shows the deliverables the customer received through their plans:
85
+
86
+ * **Files** — View and download digital files available to the customer.
87
+ * **Links** — Open private or external resource links attached to the plan.
88
+ * **License keys** — View issued license keys and use the available license-management controls.
89
+
90
+ These sections let support teams confirm access without opening each order separately.
91
+
92
+ For catalog setup, see [Digital Downloads](/product-catalog/digital-downloads), [Links](/product-catalog/links), and [License Key Management](/product-catalog/license-keys).
93
+
94
+ ### Entitlements
95
+
96
+ This view shows exactly what the customer can do right now based on their plan.
97
+
98
+ **Overrides**
99
+ You often need to make exceptions for specific users. You can do that here without changing the underlying plan.
100
+ * Change the value of a specific feature.
101
+ * Update the usage limit for a Meter feature.
102
+
103
+ Changes made here apply only to this specific customer.
104
+
105
+ <img src="/images/entitlements-details.webp" />
@@ -109,15 +109,15 @@ await kq.ready();
109
109
 
110
110
  #### Options
111
111
 
112
- | Option | Type | Description |
113
- |--------|------|-------------|
114
- | `customerId` | `string` | Unique identifier for the customer (required for entitlements) |
115
- | `productId` | `string` | Product identifier for fetching pricing data (required for pricing) |
116
- | `accessToken` | `string` | Authentication token for API requests |
112
+ | Option | Type | Default | Description |
113
+ |--------|------|---------|-------------|
114
+ | `customerId` | `string` | — | Unique identifier for the customer (required for entitlements) |
115
+ | `productId` | `string` | — | Product identifier for fetching pricing data (required for pricing) |
116
+ | `accessToken` | `string` | — | Authentication token for API requests |
117
117
  | `environment` | `sandbox\|production` | 'production' | The environment to use. If you want to use the sandbox, you must provide this. |
118
118
  | `initializeAndFetch` | `boolean` | `true` | Automatically fetch data on initialization |
119
- | `onError` | `(error: Error) => void` | Error callback function |
120
- | `mainApiUrl` | `string` | Optional override for the main API base URL (used by pricing) |
119
+ | `onError` | `(error: Error) => void` | — | Error callback function |
120
+ | `mainApiUrl` | `string` | — | Optional override for the main API base URL (used by pricing) |
121
121
 
122
122
  At least one of `customerId` or `productId` must be provided.
123
123
 
@@ -314,7 +314,7 @@ Automatically populate pricing into HTML elements using `data-kq-price` attribut
314
314
 
315
315
  ```html
316
316
  <span data-kq-price="starter" data-kq-period="MONTHLY">Loading...</span>
317
- <span data-kq-price="starter" data-kq-period="ANNUALLY">Loading...</span>
317
+ <span data-kq-price="starter" data-kq-period="YEARLY">Loading...</span>
318
318
  <span data-kq-price="free" data-kq-period="MONTHLY">Loading...</span>
319
319
  ```
320
320
 
@@ -329,7 +329,7 @@ kq.renderPricing(); // Scans DOM and populates data-kq-price elements
329
329
  ```
330
330
 
331
331
  - `data-kq-price` — the plan identifier (e.g., `"starter"`, `"pro"`)
332
- - `data-kq-period` — the charge period (e.g., `"MONTHLY"`, `"ANNUALLY"`)
332
+ - `data-kq-period` — the charge period (e.g., `"MONTHLY"`, `"YEARLY"`)
333
333
  - Free plans display `"Free"` instead of a price
334
334
  - Disabled or missing plans result in empty text
335
335
 
@@ -422,7 +422,7 @@ interface RawPricingPrice {
422
422
  }
423
423
 
424
424
  interface RawPricingCharge {
425
- chargePeriod: string; // e.g., "MONTHLY", "ANNUALLY"
425
+ chargePeriod: string; // e.g., "MONTHLY", "YEARLY"
426
426
  priceData: { amount: number };
427
427
  }
428
428
  ```
@@ -665,7 +665,7 @@ const kq = kelviqSDK({
665
665
 
666
666
  ## Using the Sandbox
667
667
 
668
- If you want to use the sandbox, you need to set the `environment` option to `sandbox` in the `init` function.
668
+ Set `environment: "sandbox"` when you call `kelviqSDK()`, and use a sandbox Client API Key.
669
669
 
670
670
  ```typescript
671
671
  const kq = kelviqSDK({
@@ -33,7 +33,7 @@ Copy your promotion ID from the promotion detail page and call `init()`:
33
33
  KQPromotionUI.init({
34
34
  // Replace with your promotion ID
35
35
  promotionId: "YOUR_PROMOTION_ID",
36
- // Access token can be found in the Settings -> API keys section
36
+ // Access token can be found in the Settings → API keys section
37
37
  accessToken: "YOUR_CLIENT_ACCESS_TOKEN",
38
38
  showBanner: true,
39
39
  });
@@ -61,7 +61,7 @@ This will automatically display a discount banner if the visitor is eligible for
61
61
  | `maximumDecimalDigits` | `number` | `2` | Maximum fraction digits (0–2) |
62
62
  | `banner.*` | object | — | Customization for the discount banner |
63
63
  | `banner.unStyled` | boolean | false | if true, no styling will be applied to the banner |
64
- | `banner.addCloseIcon`| boolean | true | Control close button visibility. This setting will work only if close button is enabled from the ParityDeals banner settings |
64
+ | `banner.addCloseIcon`| boolean | true | Shows or hides the close button. Works only when the close button is enabled in the promotion's banner settings in Kelviq. |
65
65
  | `banner.placement` | `top\|bottom` | 'top' | The placement of the discount banner |
66
66
  | `banner.container` | string | null | The container for the discount banner |
67
67
  | `banner.backgroundColor`| string | '#f0f0f0' | The background color of the discount banner |