@kelviq/mcp-server 1.2.1 → 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.
- package/README.md +40 -3
- package/dist/config.d.ts +5 -0
- package/dist/config.js +1 -0
- package/dist/config.js.map +1 -1
- package/dist/docs/ai/docs-for-agents.md +21 -0
- package/dist/docs/ai/overview.md +43 -0
- package/dist/docs/api-reference/authentication.md +9 -3
- package/dist/docs/api-reference/introduction.md +23 -2
- package/dist/docs/backend-integration/node-sdk.md +12 -6
- package/dist/docs/backend-integration/python-sdk.md +14 -8
- package/dist/docs/changelog.md +352 -3
- package/dist/docs/checkout/checkout-configuration.md +25 -75
- package/dist/docs/checkout/checkout-design.md +76 -0
- package/dist/docs/checkout/checkout-examples.md +212 -0
- package/dist/docs/checkout/checkout-metadata.md +1 -1
- package/dist/docs/checkout/custom-fields.md +60 -0
- package/dist/docs/checkout/embed-checkout.md +280 -0
- package/dist/docs/checkout/payment-methods/upi.md +69 -0
- package/dist/docs/checkout/payment-methods.md +119 -0
- package/dist/docs/checkout/static-checkout-url.md +3 -2
- package/dist/docs/cli/commands.md +57 -4
- package/dist/docs/cli/kelviq-config.md +1 -1
- package/dist/docs/cli/overview.md +1 -0
- package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
- package/dist/docs/customer-portal/overview.md +7 -7
- package/dist/docs/customer-portal/retention.md +109 -0
- package/dist/docs/customers-management/overview.md +105 -0
- package/dist/docs/frontend-integration/js-sdk.md +11 -11
- package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
- package/dist/docs/frontend-integration/react-sdk.md +8 -49
- package/dist/docs/frontend-integration/react-ui.md +8 -6
- package/dist/docs/getstarted/fees.md +27 -11
- package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
- package/dist/docs/getstarted/merchant-of-record.md +18 -24
- package/dist/docs/getstarted/overview.md +98 -0
- package/dist/docs/getstarted/review-process.md +59 -59
- package/dist/docs/guides/agent-toolkit.md +14 -9
- package/dist/docs/guides/mcp-server.md +24 -9
- package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
- package/dist/docs/guides/sandbox.md +6 -4
- package/dist/docs/guides/set-up-with-ai.md +43 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
- package/dist/docs/guides/subscription-integration.md +1 -1
- package/dist/docs/guides/test-payments.md +640 -0
- package/dist/docs/guides/webhooks.md +182 -30
- package/dist/docs/integrations/woocommerce.md +88 -0
- package/dist/docs/integrations/zapier.md +22 -0
- package/dist/docs/legal/account-and-funds.md +59 -0
- package/dist/docs/legal/approved-prohibited-policy.md +32 -27
- package/dist/docs/legal/payment-flow-diagram.md +7 -7
- package/dist/docs/manifest.json +160 -41
- package/dist/docs/openapi.json +1359 -109
- package/dist/docs/payouts/overview.md +14 -12
- package/dist/docs/payouts/payout-account.md +1 -1
- package/dist/docs/payouts/transactions.md +3 -3
- package/dist/docs/product-catalog/create-a-feature.md +3 -3
- package/dist/docs/product-catalog/digital-downloads.md +5 -5
- package/dist/docs/product-catalog/discounts.md +2 -2
- package/dist/docs/product-catalog/entitlements.md +20 -27
- package/dist/docs/product-catalog/free-and-trials.md +4 -4
- package/dist/docs/product-catalog/license-keys.md +56 -29
- package/dist/docs/product-catalog/links.md +3 -3
- package/dist/docs/product-catalog/location-based-pricing.md +6 -10
- package/dist/docs/product-catalog/one-time-payments.md +3 -7
- package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
- package/dist/docs/product-catalog/plans.md +22 -19
- package/dist/docs/product-catalog/products.md +11 -3
- package/dist/docs/product-catalog/proration.md +69 -0
- package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
- package/dist/docs/product-catalog/subscriptions.md +52 -22
- package/dist/docs/product-catalog/tax-settings.md +8 -8
- package/dist/docs/product-catalog/usage-alerts.md +7 -7
- package/dist/docs/product-catalog/usage-based-billing.md +156 -29
- package/dist/docs/product-catalog/usage-limits.md +78 -0
- package/dist/docs/promotions/create-a-promotion.md +2 -2
- package/dist/docs/promotions/overview.md +1 -1
- package/dist/docs/quickstart/core-concepts.md +36 -30
- package/dist/docs/quickstart/dashboard-setup.md +26 -22
- package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
- package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
- package/dist/docs/sales/checkout-sessions.md +28 -39
- package/dist/docs/sales/orders.md +30 -54
- package/dist/docs/settings/customer-emails.md +52 -0
- package/dist/docs/settings/members.md +27 -0
- package/dist/docs/settings/profile.md +26 -0
- package/dist/docs/settings/zapier.md +22 -0
- package/dist/http/errors.d.ts +20 -1
- package/dist/http/errors.js +83 -31
- package/dist/http/errors.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +54 -0
- package/dist/schemas/kelviq.js +64 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +3 -2
- package/dist/server.js.map +1 -1
- package/dist/tools/imports.d.ts +68 -0
- package/dist/tools/imports.js +242 -0
- package/dist/tools/imports.js.map +1 -0
- package/dist/tools/index.d.ts +2 -1
- package/dist/tools/index.js +4 -1
- package/dist/tools/index.js.map +1 -1
- 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
|
-
|
|
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
|
-
|
|
11
|
+
To get paid, connect your bank account.
|
|
12
12
|
|
|
13
13
|
|
|
14
14
|
|
|
15
|
-
|
|
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
|
|
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
|
|
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
|
-
###
|
|
47
|
+
### Do I need a Stripe account?
|
|
48
48
|
|
|
49
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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 $0.40
|
|
|
64
64
|
|
|
65
65
|
[See the complete fee table and more examples →](/getstarted/fees)
|
|
66
66
|
|
|
67
|
-
|
|
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
|
-
|
|
|
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
|
-
- **
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 &
|
|
2
|
+
title: "Features & limits (Entitlements)"
|
|
3
3
|
slug: "product-catalog/entitlements"
|
|
4
4
|
section: "product-catalog"
|
|
5
|
-
description: "
|
|
5
|
+
description: "Entitlements decide which features and limits each customer gets"
|
|
6
6
|
---
|
|
7
|
-
|
|
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
|
|
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
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
@@ -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
|
|
40
|
+
Trials work on plans with at least one recurring billing cycle.
|
|
41
41
|
|
|
42
|
-
<img
|
|
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
|
|
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
|
|
18
|
+
<img src="/images/enable-key.webp" />
|
|
19
19
|
|
|
20
|
-
1.
|
|
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
|
|
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
|
|
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
|
|
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 **
|
|
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
|
-
|
|
72
|
+
The **License** tab displays:
|
|
71
73
|
|
|
72
|
-
<img
|
|
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
|
|
83
|
+
Click the **⋯** menu button on the license card to access these options:
|
|
82
84
|
|
|
83
|
-
<img
|
|
85
|
+
<img src="/images/available-actions.webp" />
|
|
84
86
|
|
|
85
87
|
#### 🔄 Regenerate Key
|
|
86
88
|
|
|
87
|
-
<img
|
|
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
|
|
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
|
|
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
|
|
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
|
-
###
|
|
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 [
|
|
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
|
|
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
|
|
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
|
|
316
|
-
| Copy license key | Order
|
|
317
|
-
| Regenerate key | Order
|
|
318
|
-
| Change activation limit | Order
|
|
319
|
-
| Change expiry date | Order
|
|
320
|
-
| View all activations | Order
|
|
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
|
|
349
|
+
| Deactivate entire license | Order's License tab → ⋯ menu | "Deactivate" |
|
|
323
350
|
|
|
324
351
|
---
|
|
325
352
|
|
|
@@ -17,7 +17,7 @@ Use Links to share:
|
|
|
17
17
|
|
|
18
18
|
## Accessing Links
|
|
19
19
|
|
|
20
|
-
<img
|
|
20
|
+
<img src="/images/accessing-links.webp" />
|
|
21
21
|
|
|
22
22
|
1. Navigate to **Products** in the sidebar
|
|
23
23
|
2. Select the product containing your plan
|
|
@@ -31,7 +31,7 @@ The section header shows the current count of saved links (e.g., "Links (3)").
|
|
|
31
31
|
|
|
32
32
|
### How to Add a Link
|
|
33
33
|
|
|
34
|
-
<img
|
|
34
|
+
<img src="/images/adding-links.webp" />
|
|
35
35
|
|
|
36
36
|
1. Open the **Links** section
|
|
37
37
|
2. You'll see two input fields:
|
|
@@ -69,7 +69,7 @@ Choose clear, descriptive names that tell customers what they'll access:
|
|
|
69
69
|
|
|
70
70
|
### Remove a Link
|
|
71
71
|
|
|
72
|
-
<img
|
|
72
|
+
<img src="/images/remove-links.webp" />
|
|
73
73
|
|
|
74
74
|
1. Open the **Links** section
|
|
75
75
|
2. Click the **×** button next to the link you want to remove
|