@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
@@ -4,15 +4,15 @@ slug: "payouts/overview"
4
4
  section: "payouts"
5
5
  description: "Connect your bank account and track cash flow"
6
6
  ---
7
- We use Stripe to ensure you get paid fast and your tax documents are handled automatically.
7
+ Kelviq pays your earnings to your bank account. You don't need a Stripe account of your own.
8
8
 
9
9
  ## Setup
10
10
 
11
- Before you can receive funds, you need to connect a bank account.
11
+ To get paid, connect your bank account.
12
12
 
13
13
 
14
14
 
15
- Navigate to the **Payouts** group and click the **Set up payout** button.
15
+ Click **Payouts** in the sidebar, then click **Set up payouts**.
16
16
 
17
17
 
18
18
 
@@ -20,13 +20,13 @@ Before you can receive funds, you need to connect a bank account.
20
20
  You will be redirected to a secure Stripe form. Choose your account type (Individual or Company) and enter your banking details.
21
21
 
22
22
 
23
- <img height="200" src="/images/payout-setup-cta.png" alt="Payout setup screen with CTA" />
23
+ <img src="/images/payout-setup-cta.webp" alt="Payout setup screen with CTA" />
24
24
 
25
25
  ## Dashboard
26
26
 
27
27
  Once set up, the main Payouts view gives you a real-time snapshot of your cash flow.
28
28
 
29
- <img height="200" src="/images/payout-dashboard.png" alt="Payout dashboard showing available funds and processing amounts" />
29
+ <img src="/images/payout-dashboard.webp" alt="Payout dashboard showing available funds and processing amounts" />
30
30
 
31
31
  ### Key metrics
32
32
  * **Available to payout**
@@ -44,15 +44,17 @@ Below the metrics, you will see a list of every payout we have sent to your bank
44
44
 
45
45
  ## Payout questions
46
46
 
47
- ### Can I receive payouts if Stripe does not offer standalone accounts in my country?
47
+ ### Do I need a Stripe account?
48
48
 
49
- Kelviq payouts use Stripe Connect, which is separate from opening your own standalone Stripe merchant account. You may still be eligible for Kelviq payouts even if standalone Stripe accounts are not offered in your country.
49
+ No. You don't need to sign up for Stripe or have a Stripe account to sell with Kelviq or to get paid.
50
50
 
51
- Your country must appear in Kelviq's payout onboarding flow, and you must complete Stripe Connect's identity and bank-account checks. See the [supported payout countries](/getstarted/review-process#supported-payout-countries) before setting up live payments.
51
+ When you click **Set up payouts**, you verify your identity and add your bank account in a short form run by Stripe Connect. This creates a payout account that only receives your earnings from Kelviq. It's different from a regular Stripe account: you don't sell through it, and Stripe's limits on which countries can open a regular account don't apply.
52
+
53
+ That's why sellers in countries where Stripe doesn't offer its own accounts, such as India, can still use Kelviq and receive payouts. Check that your country is in the [supported payout countries](/getstarted/review-process#supported-payout-countries) before you go live.
52
54
 
53
55
  ### How long does a payout take?
54
56
 
55
- Sales funds usually become available for payout after seven days. After Kelviq sends the payout, allow another few business days for your bank to post it. Bank holidays, compliance reviews, reserves, and the receiving bank can extend this timing.
57
+ Funds from a sale are available to pay out 7 days after the payment. After Kelviq sends a payout, your bank takes a few business days to post it. Bank holidays can add time.
56
58
 
57
59
  ### What is the minimum payout?
58
60
 
@@ -60,9 +62,9 @@ The minimum payout amount is $10, or the equivalent amount in the payout currenc
60
62
 
61
63
  ### Are there payout fees?
62
64
 
63
- No. Currently, Kelviq is bearing the payout fee. You will not be charged any additional fees when your cleared Kelviq balance is sent to your bank account or eligible debit card.
65
+ No. Your full cleared balance is sent to your bank account or eligible debit card. If your bank account uses a different currency, the amount is converted when the payout is sent.
64
66
 
65
- [See the full transaction and payout fee schedule →](/getstarted/fees#payout-fees)
67
+ [See the full fee schedule →](/getstarted/fees)
66
68
 
67
69
  ### Do I need a registered company?
68
70
 
@@ -70,4 +72,4 @@ No. You can complete payout onboarding as an individual. If you are a sole propr
70
72
 
71
73
  ### Can I receive a payout in another currency?
72
74
 
73
- Yes. For example, a seller in Canada can receive a payout in USD when the connected bank account accepts USD and that payout currency is available through Stripe Connect. The payout currency follows the connected bank account. If conversion is required, Stripe applies its exchange rate and any conversion fees.
75
+ Yes. For example, a seller in Canada can receive a payout in USD when the connected bank account accepts USD and that payout currency is available through Stripe Connect. The payout currency follows the connected bank account. Kelviq charges no payout fee. If your bank account is in another currency, Stripe converts the payout at its exchange rate, which can include a conversion fee.
@@ -6,7 +6,7 @@ description: "Manage bank accounts and transfer schedules"
6
6
  ---
7
7
  The **Payout Account** tab lets you control how and when you get paid.
8
8
 
9
- <img height="200" src="/images/payout-settings.png" alt="Payout settings showing bank account and schedule preferences" />
9
+ <img src="/images/payout-settings.webp" alt="Payout settings showing bank account and schedule preferences" />
10
10
 
11
11
  ## Bank account
12
12
  View the currently connected bank account. You can also click the link to view your full verification status directly on Stripe.
@@ -6,7 +6,7 @@ description: "Audit individual payments, fees, and net earnings"
6
6
  ---
7
7
  The **Transactions** tab shows successful payments, refunds, and failed payments. Use it to see what the customer paid, the fees and tax deducted, and the amount added to your balance.
8
8
 
9
- <img height="200" src="/images/payout-transactions-list.png" alt="List of individual transactions with status filters" />
9
+ <img src="/images/payout-transactions-list.webp" alt="List of individual transactions with status filters" />
10
10
 
11
11
  ## Filtering
12
12
 
@@ -26,7 +26,7 @@ Click a transaction row to open its details.
26
26
  * **Gross total:** The full amount charged to the customer, including tax.
27
27
  * **Fee:** The combined transaction fees deducted by Kelviq.
28
28
  * **Tax:** Tax collected for the transaction and excluded from your net earnings.
29
- * **Net earnings:** The amount added to your Kelviq balance after transaction fees and tax. A separate payout fee can apply when the balance is sent to your bank.
29
+ * **Net earnings:** The amount added to your Kelviq balance after transaction fees and tax. There's no payout fee, so nothing more is deducted when the balance is sent to your bank.
30
30
  * **Payment details:** The card or method used.
31
31
 
32
32
  For a successful transaction:
@@ -64,4 +64,4 @@ The percentage is calculated from the gross customer charge. The fixed &#36;0.40
64
64
 
65
65
  [See the complete fee table and more examples →](/getstarted/fees)
66
66
 
67
- Payout fees are not included in the **Fee** column for a customer transaction. They apply when funds are sent to your bank account. See [Payout fees](/getstarted/fees#payout-fees).
67
+ There's no payout fee. See [Payout fees](/getstarted/fees#payout-fees).
@@ -12,7 +12,7 @@ Create the feature once, then reuse it across plans. Creating a feature does not
12
12
 
13
13
  | Dashboard option | API value | Use it for |
14
14
  | --- | --- | --- |
15
- | Switch/boolean | `BOOLEAN` | On-or-off access, such as analytics, SSO, or priority support |
15
+ | Boolean | `BOOLEAN` | On-or-off access, such as analytics, SSO, or priority support |
16
16
  | Meter | `METER` | A quantity that is purchased or consumed, such as seats, API calls, storage, or credits |
17
17
  | Customizable | `CUSTOMIZABLE` | A plan-specific numeric limit or setting, such as maximum projects or upload size |
18
18
 
@@ -26,7 +26,7 @@ Create the feature once, then reuse it across plans. Creating a feature does not
26
26
  4. Enter an **Identifier**. Your application uses this value when checking access or reporting usage.
27
27
  5. Add a **Description** if your team needs more context about what the feature controls.
28
28
  6. Choose the **Feature type**:
29
- - **Switch/boolean** for on-or-off access.
29
+ - **Boolean** for on-or-off access.
30
30
  - **Meter** for purchased or consumed quantities.
31
31
  - **Customizable** for a numeric limit or setting.
32
32
  7. For a Meter feature, enter the singular and plural units. For example, use `call` and `calls`, or `seat` and `seats`.
@@ -100,7 +100,7 @@ The feature remains independent until you attach it to a plan:
100
100
  - Set the limit, reset cadence, hard-limit behavior, rollover, or alerts for a Meter feature.
101
101
  6. Save the plan. Publish the draft when it is ready for customers.
102
102
 
103
- Read [Features and limits](/product-catalog/entitlements) to check access from your application, [Usage-based pricing](/product-catalog/usage-based-billing) to price metered consumption, or [Seat-based pricing](/product-catalog/seat-based-pricing) to sell purchased quantities.
103
+ Read [Features & limits](/product-catalog/entitlements) to check access from your application, [Usage-based pricing](/product-catalog/usage-based-billing) to price metered consumption, or [Seat-based pricing](/product-catalog/seat-based-pricing) to sell purchased quantities.
104
104
 
105
105
  ## Common problems
106
106
 
@@ -17,7 +17,7 @@ Use Digital Downloads to deliver:
17
17
 
18
18
  ## Accessing Digital Downloads
19
19
 
20
- <img height="200" src="/images/accessing-digital-downloads.png" />
20
+ <img src="/images/accessing-digital-downloads.webp" />
21
21
 
22
22
  1. Navigate to **Products** in the sidebar
23
23
  2. Select the product containing your plan
@@ -29,7 +29,7 @@ Use Digital Downloads to deliver:
29
29
 
30
30
  ### How to Upload
31
31
 
32
- <img height="200" src="/images/uploading-files.png" />
32
+ <img src="/images/uploading-files.webp" />
33
33
 
34
34
  1. Open the **Digital downloads** section
35
35
  2. Click anywhere in the upload area, or drag and drop files directly
@@ -39,7 +39,7 @@ Use Digital Downloads to deliver:
39
39
 
40
40
  ### Upload Progress
41
41
 
42
- <img height="200" src="/images/upload-progress.png" />
42
+ <img src="/images/upload-progress.webp" />
43
43
 
44
44
  While uploading, you'll see:
45
45
  - File name and size
@@ -69,7 +69,7 @@ Each uploaded file has a toggle switch and a menu button (**⋯**) with addition
69
69
 
70
70
  You can temporarily hide files from customers without deleting them:
71
71
 
72
- <img height="200" src="/images/enable-disable-files.png" />
72
+ <img src="/images/enable-disable-files.webp" />
73
73
 
74
74
  1. Find the file in the uploads list
75
75
  2. Click the toggle switch next to the file
@@ -82,7 +82,7 @@ This is useful when you need to temporarily remove access to a file or prepare f
82
82
 
83
83
  Click the menu button (**⋯**) next to any file to access additional options:
84
84
 
85
- <img height="200" src="/images/managing-files.png" />
85
+ <img src="/images/managing-files.webp" />
86
86
 
87
87
  #### Download
88
88
 
@@ -39,7 +39,7 @@ For a fixed-amount discount, select the currency next to the amount. Kelviq plac
39
39
  Click **Create discount** to make the code live immediately.
40
40
 
41
41
 
42
- <img height="200" src="/images/create-discount-modal.png" alt="Discount creation modal showing percentage and code options" />
42
+ <img src="/images/create-discount-modal.webp" alt="Discount creation modal showing percentage and code options" />
43
43
 
44
44
  ## Configuration options
45
45
 
@@ -76,7 +76,7 @@ Customers can enter a code themselves, or you can pre-apply one through the Chec
76
76
 
77
77
  The main discounts tab shows the status of every code you have created.
78
78
 
79
- <img height="200" src="/images/discounts-list.png" alt="List of active and expired discounts" />
79
+ <img src="/images/discounts-list.webp" alt="List of active and expired discounts" />
80
80
 
81
81
  * **Active:** The code is live and redeemable.
82
82
  * **Expired:** The code has passed its end date or hit its usage limit.
@@ -1,12 +1,12 @@
1
1
  ---
2
- title: "Features & Limits (Entitlements)"
2
+ title: "Features & limits (Entitlements)"
3
3
  slug: "product-catalog/entitlements"
4
4
  section: "product-catalog"
5
- description: "Control feature access for your customers"
5
+ description: "Entitlements decide which features and limits each customer gets"
6
6
  ---
7
- Entitlements are the modern way to control feature access in your application. Instead of checking which plan a customer is on, you check which features they have access to. This fundamental shift gives you unprecedented flexibility to experiment with pricing, create custom deals, and iterate on your product—all without changing code.
7
+ Check features, not plans. Your code asks whether a customer has a feature, and Kelviq answers from their plan. You can change plans, prices, and custom deals without changing code. In the API and SDKs, a feature on a plan is called an entitlement.
8
8
 
9
- <img height="200" src="/images/features-limits-enttilements.png" />
9
+ <img src="/images/features-limits-enttilements.webp" />
10
10
 
11
11
  For SDK installation and API reference, see:
12
12
  - [Node SDK Documentation](https://docs.kelviq.com/backend-integration/node-sdk)
@@ -36,7 +36,6 @@ This approach has serious limitations:
36
36
  - **Code changes required** for any pricing restructure
37
37
  - **Deployment needed** to move a feature between plans
38
38
  - **Engineering bottleneck** for every pricing experiment
39
- - **Webhook complexity** to sync subscription state
40
39
  - **Stale cache issues** when plans change
41
40
  - **Custom deals are painful** requiring one-off code
42
41
 
@@ -68,14 +67,14 @@ Now you can:
68
67
 
69
68
  ### The Flow
70
69
 
71
- <img height="200" src="/images/features-kelviq-dashboard.png" />
70
+ <img src="/images/features-kelviq-dashboard.webp" />
72
71
 
73
72
  1) Setup plans and features on Kelviq Dashboard
74
73
  1) When a customer completes checkout, their entitlements are automatically assigned.
75
74
  1) Your app checks access via SDK
76
75
  1) Customer gets immediate access
77
76
 
78
- ### No Webhooks Required
77
+ ### Access right after checkout
79
78
 
80
79
  When a customer completes checkout:
81
80
 
@@ -84,11 +83,7 @@ When a customer completes checkout:
84
83
  3. Your app checks access via SDK
85
84
  4. Customer gets immediate access
86
85
 
87
- You don't need to:
88
- - Build webhook handlers
89
- - Sync subscription state to your database
90
- - Handle race conditions
91
- - Manage cache invalidation
86
+ Your app checks access with Kelviq, so you don't have to copy subscription state into your own database. If you want to react to changes in your own systems, use [webhooks](/guides/webhooks).
92
87
 
93
88
  ---
94
89
 
@@ -98,13 +93,13 @@ Kelviq serves entitlement checks through its edge API. The service targets P95 r
98
93
 
99
94
  ### Node and Python SDK fallback
100
95
 
101
- The current Node and Python SDKs cache entitlement responses by default. Each process keeps a fresh in-memory entry for 60 seconds. If the edge API is unreachable or returns a server error, the SDK can return the last known entitlement state instead of failing the access check.
96
+ The Node and Python SDKs cache entitlement responses for 60 seconds in each process. If the edge API doesn't respond or returns a server error, they return the last known entitlement state instead of failing the access check.
102
97
 
103
98
  The in-memory cache is local to one process and is lost when that process restarts. For multiple application instances, workers, or containers, configure the optional Redis store. It shares the cache across instances and keeps the fallback state available through application restarts.
104
99
 
105
100
  Usage and event reports that fail because of a temporary network problem are queued. The SDK retries them on the next report call, or you can flush the queue explicitly. An in-memory queue is suitable for one process; use Redis when the queue must be shared and durable.
106
101
 
107
- The SDK cannot return a last known value for a customer or feature that has never been fetched. Decide whether your application should deny access, allow limited access, or show a temporary error when no cached state exists.
102
+ The fallback covers customers and features the SDK has already checked. For a first-time check, choose whether to deny access, allow limited access, or show a retry message.
108
103
 
109
104
  See the [Node SDK caching configuration](/backend-integration/node-sdk#caching-and-offline-resilience) or [Python SDK caching configuration](/backend-integration/python-sdk#caching-and-offline-resilience) for setup examples.
110
105
 
@@ -112,7 +107,7 @@ See the [Node SDK caching configuration](/backend-integration/node-sdk#caching-a
112
107
 
113
108
  If you call the Entitlement API without an SDK, keep your own last-known response in an in-memory or persistent cache. Store when the value was fetched, set a maximum fallback age that matches the risk of the feature, and refresh the record after the API recovers.
114
109
 
115
- Use a short fallback window for high-risk actions such as exporting sensitive data or using an expensive metered feature. A longer window may be reasonable for low-risk interface features. Do not silently grant access when there is no previous entitlement state.
110
+ Use a short fallback window for high-risk actions such as exporting sensitive data or using an expensive Meter feature. A longer window may be reasonable for low-risk interface features. Do not silently grant access when there is no previous entitlement state.
116
111
 
117
112
  If your architecture already maintains subscription state through webhooks, you can continue using that model. Process webhook events idempotently and reconcile the local record against the Entitlement API after an outage.
118
113
 
@@ -126,7 +121,7 @@ Kelviq supports three types of features to cover all access control scenarios.
126
121
 
127
122
  Simple on/off access control.
128
123
 
129
- <img height="200" src="/images/boolean.png" />
124
+ <img src="/images/boolean.webp" />
130
125
 
131
126
  **Use for:**
132
127
  - Feature flags (SSO, API access, white-labeling)
@@ -146,7 +141,7 @@ Simple on/off access control.
146
141
 
147
142
  Usage-based features with limits and tracking.
148
143
 
149
- <img height="200" src="/images/raw-meter(empty-state).png" />
144
+ <img src="/images/raw-meter(empty-state).webp" />
150
145
 
151
146
  **Use for:**
152
147
  - API calls, requests, or operations
@@ -165,7 +160,7 @@ Usage-based features with limits and tracking.
165
160
  | **Soft Limit** | Allow overages but notify/warn |
166
161
  | **Rollover** | Carry unused quota to next period |
167
162
 
168
- <img height="200" src="/images/aggregate-meter.png" />
163
+ <img src="/images/aggregate-meter.webp" />
169
164
 
170
165
  **Example configuration:**
171
166
 
@@ -179,7 +174,7 @@ Usage-based features with limits and tracking.
179
174
 
180
175
  Dynamic values that aren't simple on/off or numeric limits.
181
176
 
182
- <img height="200" src="/images/customizable.png" />
177
+ <img src="/images/customizable.webp" />
183
178
 
184
179
  **Use for:**
185
180
  - Configuration values
@@ -190,9 +185,9 @@ Dynamic values that aren't simple on/off or numeric limits.
190
185
 
191
186
  ## Soft Limits vs. Hard Limits
192
187
 
193
- Choose the right enforcement strategy for each feature.
188
+ Choose the right enforcement strategy for each feature. [How usage limits work](/product-catalog/usage-limits) walks through resets, overage, and what happens at the limit.
194
189
 
195
- <img height="200" src="/images/hard-limit.png" />
190
+ <img src="/images/hard-limit.webp" />
196
191
 
197
192
  ### Hard Limits
198
193
 
@@ -252,8 +247,7 @@ After successful payment:
252
247
 
253
248
  1. Customer record is created/updated
254
249
  2. Plan entitlements are assigned instantly
255
- 3. No webhook processing needed
256
- 4. Customer can access features immediately
250
+ 3. Customer can access features immediately
257
251
 
258
252
  ---
259
253
 
@@ -384,7 +378,7 @@ Overrides are:
384
378
  For meter features, you can reset a customer's usage:
385
379
 
386
380
  1. Go to the customer's detail page
387
- 2. Find the meter feature
381
+ 2. Find the Meter feature
388
382
  3. Click the menu (⋯) → **Reset usage**
389
383
 
390
384
  This sets their current usage back to 0, giving them their full quota again.
@@ -435,7 +429,6 @@ When you set up inheritance:
435
429
  #### Successful Purchase
436
430
  - Entitlements assigned immediately
437
431
  - Customer can access features right away
438
- - No webhook handling required
439
432
 
440
433
  #### Upgrade
441
434
  - New plan entitlements replace old ones
@@ -454,10 +447,10 @@ When you set up inheritance:
454
447
  #### Failed Payment
455
448
  - A failed card renewal moves the subscription to `past_due`
456
449
  - Kelviq retries card payments for up to 14 days before cancellation
457
- - Failed non-card renewals are not retried and the subscription is cancelled
450
+ - Card and UPI AutoPay renewals are retried for up to 14 days. If payment still fails, the subscription is canceled
458
451
 
459
452
  #### Refund
460
- - Cancelling mid-period does not automatically create a refund
453
+ - You decide whether to refund a mid-period cancellation
461
454
  - The merchant decides whether to issue a full, partial, or no refund
462
455
 
463
456
  Manage subscriptions programmatically using the [Subscriptions API](https://docs.kelviq.com/backend-integration/node-sdk#subscriptions).
@@ -6,13 +6,13 @@ description: "Set up lead magnets and trial periods"
6
6
  ---
7
7
  You do not always need to charge upfront. Kelviq lets you offer completely free plans or time restricted trials to help acquire users.
8
8
 
9
- <img height="200" src="/images/configure-price.png" />
9
+ <img src="/images/configure-price-plain.webp" />
10
10
 
11
11
  ## Free plans
12
12
 
13
13
  Use a free plan to offer a permanent zero cost tier. This is perfect for open source products, lead magnets, or a basic hobby tier where you want to gather signups without requiring a credit card.
14
14
 
15
- <img height="200" src="/images/free-paid.png" />
15
+ <img src="/images/free-paid.webp" />
16
16
 
17
17
  1. Open your draft plan
18
18
  2. Toggle the switch in the top right from Paid to Free
@@ -27,7 +27,7 @@ Entitlement checks return `false` for a customer Kelviq has never seen, so a fre
27
27
  1. Create the customer **with an email address** — `customers.create` in the SDK, or `POST /customers/`.
28
28
  2. Create the subscription — `POST /subscriptions/create/` with the plan's identifier and `chargePeriod: "ONE_TIME"`.
29
29
 
30
- Keep that order. Creating a subscription for a customer Kelviq has not seen fails with `Subscription requires a customer with a valid email address` — and the failed attempt still registers the customer, without an email. From then on `POST /customers/` answers `Customer already exists`, and the portal refuses that customer too. Recover by patching the email onto the existing record with `PATCH /customers/{customerId}/`, after which the subscription call succeeds. Treat `Customer already exists` as a signal to patch rather than an error to surface.
30
+ Keep that order, and enrol at signup, before the customer reaches checkout. Creating a subscription for a customer Kelviq has not seen fails with `Subscription requires a customer with a valid email address` — and the failed attempt still registers the customer, without an email. Creating a checkout session with a `customerId` registers the customer the same way. From then on `POST /customers/` answers `Customer already exists`, and the portal refuses that customer too. Recover by patching the email onto the existing record with `PATCH /customers/{customerId}/`, after which the subscription call succeeds. Treat `Customer already exists` as a signal to patch rather than an error to surface.
31
31
 
32
32
  Enrolling this way also records a $0 order for the plan.
33
33
 
@@ -37,9 +37,9 @@ Check for an existing subscription first, with `customer_id` on `GET /subscripti
37
37
 
38
38
  Free trials let customers test a paid plan for a specific number of days before their card is charged.
39
39
 
40
- Trials are available only when the plan has at least one recurring billing cycle. A one-time-only plan does not show trial settings and will not display a trial at checkout.
40
+ Trials work on plans with at least one recurring billing cycle.
41
41
 
42
- <img height="200" src="/images/billing-cycle.png" />
42
+ <img src="/images/billing-cycle.webp" />
43
43
 
44
44
  1. Open a paid plan draft.
45
45
  2. Enable at least one recurring billing cycle, such as **28 days**, **Monthly**, or **Yearly**.
@@ -8,16 +8,16 @@ License keys allow you to generate unique activation keys for each customer purc
8
8
 
9
9
  ---
10
10
 
11
- <img height="200" src="/images/accessing-key.png" />
11
+ <img src="/images/accessing-key.webp" />
12
12
 
13
13
  ## 1. Enabling Licenses on a Plan
14
14
 
15
15
  License keys are configured at the **plan level**. When enabled, every order placed for that plan will automatically generate a unique license key for the customer.
16
16
  ### How to Enable Licenses
17
17
 
18
- <img height="200" src="/images/enable-key.png" />
18
+ <img src="/images/enable-key.webp" />
19
19
 
20
- 1. Navigate to **Products** → Select your product → Select the plan you want to configure
20
+ 1. Go to **Product catalog → Products** → Select your product → Select the plan you want to configure
21
21
  2. Scroll down to the **License keys** section
22
22
  3. Toggle the switch to **enable** license keys
23
23
 
@@ -29,7 +29,7 @@ Once enabled, you can configure the following settings:
29
29
 
30
30
  Control how many times a single license key can be activated across different devices.
31
31
 
32
- <img height="200" src="/images/set-limit.png" />
32
+ <img src="/images/set-limit.webp" />
33
33
 
34
34
  | Setting | Description |
35
35
  |---------|-------------|
@@ -42,7 +42,7 @@ Control how many times a single license key can be activated across different de
42
42
 
43
43
  Define how long the license key remains valid after purchase.
44
44
 
45
- <img height="200" src="/images/set-duration.png" />
45
+ <img src="/images/set-duration.webp" />
46
46
 
47
47
  | Setting | Description |
48
48
  |---------|-------------|
@@ -61,15 +61,17 @@ After configuring the settings, click **Save Changes**. All future orders for th
61
61
 
62
62
  ---
63
63
 
64
- ## 2. Managing Licenses from Order Details
64
+ ## 2. Managing licenses from an order
65
65
 
66
- Once a customer places an order for a plan with licenses enabled, you can manage their license from the **Order Details** page.
66
+ Once a customer places an order for a plan with licenses enabled, you can manage their license from the order. Go to **Sales → Orders**, click the customer, and open the **License** tab.
67
+
68
+ <img src="/images/managing-licenses-from-order-details.webp" />
67
69
 
68
70
  ### Viewing License Information
69
71
 
70
- Navigate to **Orders** → Click on an order to view details. The license section displays:
72
+ The **License** tab displays:
71
73
 
72
- <img height="200" src="/images/managing-licenses-from-order-details.png" />
74
+ <img src="/images/license-tab.webp" />
73
75
 
74
76
  - **License Key**: The unique key assigned to this order
75
77
  - **Expiry Date**: When the license expires (or "Never expires")
@@ -78,13 +80,13 @@ Navigate to **Orders** → Click on an order to view details. The license sectio
78
80
 
79
81
  ### Available Actions
80
82
 
81
- Click the **⋮** menu button on the license card to access these options:
83
+ Click the **⋯** menu button on the license card to access these options:
82
84
 
83
- <img height="200" src="/images/available-actions.png" />
85
+ <img src="/images/available-actions.webp" />
84
86
 
85
87
  #### 🔄 Regenerate Key
86
88
 
87
- <img height="200" src="/images/regenerat-key.png" />
89
+ <img src="/images/regenerat-key.webp" />
88
90
 
89
91
  Creates a brand new license key and invalidates the old one.
90
92
 
@@ -96,7 +98,7 @@ Creates a brand new license key and invalidates the old one.
96
98
 
97
99
  #### ✏️ Edit Activation Limit
98
100
 
99
- <img height="200" src="/images/edit-activation-limit-1.png" />
101
+ <img src="/images/edit-activation-limit-1.webp" />
100
102
 
101
103
  Modify how many devices can use this specific license.
102
104
 
@@ -108,7 +110,7 @@ Modify how many devices can use this specific license.
108
110
 
109
111
  #### 📅 Manage Expiry
110
112
 
111
- <img height="200" src="/images/manage-expiry.png" />
113
+ <img src="/images/manage-expiry.webp" />
112
114
 
113
115
  Update the license expiration date.
114
116
 
@@ -139,7 +141,7 @@ Click on the license card to view the **License Details** page, which shows:
139
141
 
140
142
  #### Revoking Individual Activations
141
143
 
142
- <img height="200" src="/images/revoke-license.png" />
144
+ <img src="/images/revoke-license.webp" />
143
145
 
144
146
  For each active instance, you can click **Revoke** to:
145
147
  - Remove that specific instance's access
@@ -154,7 +156,26 @@ For each active instance, you can click **Revoke** to:
154
156
 
155
157
  Your customers (or their software) can interact with licenses using these API endpoints. Use these to integrate license checking into your application.
156
158
 
157
- ### 3.0 Reading a customer's key from your server
159
+ ### Authentication
160
+
161
+ The Activate, Validate, and Deactivate License APIs accept either a **Client API Key** or a **Server API Key** as a Bearer token:
162
+
163
+ ```bash
164
+ Authorization: Bearer YOUR_API_KEY
165
+ ```
166
+
167
+ Choose the key based on where the request originates:
168
+
169
+ | Request origin | API key | Guidance |
170
+ | --- | --- | --- |
171
+ | Browser, desktop app, mobile app, CLI, or plugin | Client API Key | Safe to include in distributed client software. The customer still supplies the license key. |
172
+ | Your backend or another trusted server | Server API Key | Keep it secret and load it from your server environment. |
173
+
174
+ Both key types can call `POST /license/activate/`, `POST /license/validate/`, and `POST /license/deactivate/`. Use a key from the same environment as the license: a sandbox key with a sandbox license, or a production key with a production license.
175
+
176
+ Never expose a Server API Key in frontend code or software distributed to customers. Use a Client API Key for those integrations.
177
+
178
+ ### Reading a customer's key from your server
158
179
 
159
180
  A customer's keys come back with their purchase records, authenticated with your server API key. Orders, subscriptions and invoices all carry a `license` array, and each entry holds `licenseKey` alongside `activationUsage`, `activationLimit` and `expiresOn`.
160
181
 
@@ -169,7 +190,9 @@ This matters for how much you ask of the customer. A signed-in web app already k
169
190
 
170
191
  Activates a license key on a specific device/instance.
171
192
 
172
- **Endpoint**: `POST /license/activate`
193
+ **Endpoint**: `POST /license/activate/`
194
+
195
+ **Authentication**: Client API Key or Server API Key
173
196
 
174
197
  **When to use**:
175
198
  - When the user enters their license key for the first time
@@ -195,7 +218,9 @@ Activates a license key on a specific device/instance.
195
218
 
196
219
  Checks if a license is valid and currently active.
197
220
 
198
- **Endpoint**: `POST /license/validate`
221
+ **Endpoint**: `POST /license/validate/`
222
+
223
+ **Authentication**: Client API Key or Server API Key
199
224
 
200
225
  **When to use**:
201
226
  - On application startup to verify the license
@@ -223,7 +248,9 @@ Checks if a license is valid and currently active.
223
248
 
224
249
  Removes an activation from a specific device/instance.
225
250
 
226
- **Endpoint**: `POST /license/deactivate`
251
+ **Endpoint**: `POST /license/deactivate/`
252
+
253
+ **Authentication**: Client API Key or Server API Key
227
254
 
228
255
  **When to use**:
229
256
  - When the user uninstalls your application
@@ -258,7 +285,7 @@ Removes an activation from a specific device/instance.
258
285
  6. License is now active on customer's device
259
286
  ```
260
287
 
261
- For software the customer signs in to, skip steps 3 and 4: read the key from their subscription as in [3.0](#3-0-reading-a-customer-s-key-from-your-server) and call Activate for them.
288
+ For software the customer signs in to, skip steps 3 and 4: read the key from their order or subscription as in [Reading a customer's key](#reading-a-customers-key-from-your-server) and call Activate for them.
262
289
 
263
290
  ### Workflow B: Customer Switches Devices
264
291
 
@@ -285,7 +312,7 @@ For software the customer signs in to, skip steps 3 and 4: read the key from the
285
312
 
286
313
  ```
287
314
  1. Customer requests extension
288
- 2. Admin opens Order Details
315
+ 2. Admin opens the order's License tab
289
316
  3. Click license menu → "Manage expiry"
290
317
  4. Select new expiration date
291
318
  5. Save changes
@@ -296,7 +323,7 @@ For software the customer signs in to, skip steps 3 and 4: read the key from the
296
323
 
297
324
  ```
298
325
  1. Admin notices suspicious activity (too many activations)
299
- 2. Open Order Details → View License Details
326
+ 2. Open the order's License tab
300
327
  3. Revoke unauthorized instances
301
328
  4. If key is widely leaked: Regenerate the key
302
329
  5. Send new key to legitimate customer
@@ -312,14 +339,14 @@ For software the customer signs in to, skip steps 3 and 4: read the key from the
312
339
  | Enable licenses for a plan | Plan Details | Toggle "License keys" switch |
313
340
  | Set activation limit (plan) | Plan Details → License keys | Enable limit + set number |
314
341
  | Set expiry duration (plan) | Plan Details → License keys | Enable expiry + set duration |
315
- | View customer's license | Order Details | See license card |
316
- | Copy license key | Order Details | Click on license key |
317
- | Regenerate key | Order Details → License menu | "Regenerate key" |
318
- | Change activation limit | Order Details → License menu | "Edit activation limit" |
319
- | Change expiry date | Order Details → License menu | "Manage expiry" |
320
- | View all activations | Order Details | Click license card |
342
+ | View customer's license | Order's License tab | See license card |
343
+ | Copy license key | Order's License tab | Click on license key |
344
+ | Regenerate key | Order's License tab → ⋯ menu | "Regenerate key" |
345
+ | Change activation limit | Order's License tab → ⋯ menu | "Edit activation limit" |
346
+ | Change expiry date | Order's License tab → ⋯ menu | "Manage expiry" |
347
+ | View all activations | Order's License tab | Click license card |
321
348
  | Revoke a device | License Details | Click "Revoke" on instance |
322
- | Deactivate entire license | Order Details → License menu | "Deactivate" |
349
+ | Deactivate entire license | Order's License tab → ⋯ menu | "Deactivate" |
323
350
 
324
351
  ---
325
352