@kelviq/mcp-server 0.4.0 → 1.0.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 +34 -26
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +114 -34
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +102 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/server.js +10 -1
- package/dist/server.js.map +1 -1
- package/package.json +1 -1
|
@@ -41,3 +41,33 @@ Below the metrics, you will see a list of every payout we have sent to your bank
|
|
|
41
41
|
* Check the status of past transfers.
|
|
42
42
|
* See the exact date the funds landed.
|
|
43
43
|
* View the destination bank account for each transfer.
|
|
44
|
+
|
|
45
|
+
## Payout questions
|
|
46
|
+
|
|
47
|
+
### Can I receive payouts if Stripe does not offer standalone accounts in my country?
|
|
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.
|
|
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.
|
|
52
|
+
|
|
53
|
+
### How long does a payout take?
|
|
54
|
+
|
|
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.
|
|
56
|
+
|
|
57
|
+
### What is the minimum payout?
|
|
58
|
+
|
|
59
|
+
The minimum payout amount is $10, or the equivalent amount in the payout currency.
|
|
60
|
+
|
|
61
|
+
### Are there payout fees?
|
|
62
|
+
|
|
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.
|
|
64
|
+
|
|
65
|
+
[See the full transaction and payout fee schedule →](/getstarted/fees#payout-fees)
|
|
66
|
+
|
|
67
|
+
### Do I need a registered company?
|
|
68
|
+
|
|
69
|
+
No. You can complete payout onboarding as an individual. If you are a sole proprietor and do not have a separate registered company, select **Individual** and provide your own legal and tax details.
|
|
70
|
+
|
|
71
|
+
### Can I receive a payout in another currency?
|
|
72
|
+
|
|
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.
|
|
@@ -4,20 +4,64 @@ slug: "payouts/transactions"
|
|
|
4
4
|
section: "payouts"
|
|
5
5
|
description: "Audit individual payments, fees, and net earnings"
|
|
6
6
|
---
|
|
7
|
-
The **Transactions** tab
|
|
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
9
|
<img height="200" src="/images/payout-transactions-list.png" alt="List of individual transactions with status filters" />
|
|
10
10
|
|
|
11
11
|
## Filtering
|
|
12
|
-
|
|
12
|
+
|
|
13
|
+
You can filter the list by status to find specific issues.
|
|
14
|
+
|
|
13
15
|
* **Success:** Completed payments.
|
|
16
|
+
* **Pending:** Payments that have not finished processing.
|
|
14
17
|
* **Refunded:** Money returned to customers.
|
|
15
18
|
* **Failed:** Declined cards or failed transfers.
|
|
16
19
|
|
|
20
|
+
The search field also matches payment method types. Search for `upi`, `card`, `link`, `amazon_pay`, or `sepa_debit` to see payments made through that method.
|
|
21
|
+
|
|
17
22
|
## Transaction details
|
|
18
|
-
Click on any transaction row to open the details view. This breaks down the math so you know exactly what you earned from that specific order.
|
|
19
23
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
* **
|
|
24
|
+
Click a transaction row to open its details.
|
|
25
|
+
|
|
26
|
+
* **Gross total:** The full amount charged to the customer, including tax.
|
|
27
|
+
* **Fee:** The combined transaction fees deducted by Kelviq.
|
|
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.
|
|
23
30
|
* **Payment details:** The card or method used.
|
|
31
|
+
|
|
32
|
+
For a successful transaction:
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
Net = Gross - Fee - Tax
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## How the Fee column is calculated
|
|
39
|
+
|
|
40
|
+
The **Fee** column shows one combined amount. Depending on the transaction, that amount can contain up to three components:
|
|
41
|
+
|
|
42
|
+
| Component | Rate | When it applies |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| Base fee before $5,000 in total volume | 2.9% + $0.40 | Transactions processed before your organization reaches $5,000 in cumulative sales |
|
|
45
|
+
| Base fee after $5,000 in total volume | 3.5% + $0.40 | Subsequent transactions after your organization reaches $5,000 in cumulative sales |
|
|
46
|
+
| Recurring billing | +0.7% | Subscription payments and renewals |
|
|
47
|
+
| International card | +1.5% | Cards issued outside the United States |
|
|
48
|
+
|
|
49
|
+
Recurring and international-card fees are added to the base rate when they apply. For example, an international subscription payment processed after the $5,000 threshold is charged 5.7% + $0.40: 3.5% base, 0.7% recurring, and 1.5% international.
|
|
50
|
+
|
|
51
|
+
### Example from the transaction list
|
|
52
|
+
|
|
53
|
+
For a $57.60 domestic, one-time payment processed after the $5,000 threshold:
|
|
54
|
+
|
|
55
|
+
```text
|
|
56
|
+
Fee = ($57.60 × 3.5%) + $0.40
|
|
57
|
+
= $2.42 after rounding
|
|
58
|
+
|
|
59
|
+
Net = $57.60 gross - $2.42 fee - $9.60 tax
|
|
60
|
+
= $45.58
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The percentage is calculated from the gross customer charge. The fixed $0.40 is added once. Kelviq rounds the final fee to the smallest unit of the transaction currency.
|
|
64
|
+
|
|
65
|
+
[See the complete fee table and more examples →](/getstarted/fees)
|
|
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).
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Create a feature in Kelviq"
|
|
3
|
+
slug: "product-catalog/create-a-feature"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Create Boolean, Meter, or Customizable features in the Kelviq dashboard or with the API, then add them to a plan as entitlements."
|
|
6
|
+
---
|
|
7
|
+
A feature is something your product can enable, limit, or measure for a customer. Examples include analytics access, team size, API calls, storage, and AI credits.
|
|
8
|
+
|
|
9
|
+
Create the feature once, then reuse it across plans. Creating a feature does not grant it to anyone. You must add it to a plan as an entitlement before customers receive access.
|
|
10
|
+
|
|
11
|
+
## Choose a feature type
|
|
12
|
+
|
|
13
|
+
| Dashboard option | API value | Use it for |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| Switch/boolean | `BOOLEAN` | On-or-off access, such as analytics, SSO, or priority support |
|
|
16
|
+
| Meter | `METER` | A quantity that is purchased or consumed, such as seats, API calls, storage, or credits |
|
|
17
|
+
| Customizable | `CUSTOMIZABLE` | A plan-specific numeric limit or setting, such as maximum projects or upload size |
|
|
18
|
+
|
|
19
|
+
Use an identifier that is short, stable, and easy to use in code, such as `api-calls` or `advanced-analytics`. You can rename a feature later, but its identifier and type cannot be changed after creation.
|
|
20
|
+
|
|
21
|
+
## Method 1: Create a feature in the dashboard
|
|
22
|
+
|
|
23
|
+
1. Open **Product catalog → Features** in the [Kelviq dashboard](https://app.kelviq.com/features).
|
|
24
|
+
2. Click **Create feature**.
|
|
25
|
+
3. Enter a **Feature name**. This is the readable name shown in the dashboard.
|
|
26
|
+
4. Enter an **Identifier**. Your application uses this value when checking access or reporting usage.
|
|
27
|
+
5. Add a **Description** if your team needs more context about what the feature controls.
|
|
28
|
+
6. Choose the **Feature type**:
|
|
29
|
+
- **Switch/boolean** for on-or-off access.
|
|
30
|
+
- **Meter** for purchased or consumed quantities.
|
|
31
|
+
- **Customizable** for a numeric limit or setting.
|
|
32
|
+
7. For a Meter feature, enter the singular and plural units. For example, use `call` and `calls`, or `seat` and `seats`.
|
|
33
|
+
8. Click **Create**.
|
|
34
|
+
|
|
35
|
+
Turn on **Create more** before saving if you want the form to remain open for another feature.
|
|
36
|
+
|
|
37
|
+
The dashboard creates Meter features for pre-aggregated usage. Your application reports the quantity with the usage reporting API or an SDK. A purchased quantity such as seats can also come from checkout or a subscription update.
|
|
38
|
+
|
|
39
|
+
## Method 2: Create a feature with the API
|
|
40
|
+
|
|
41
|
+
Use the Catalog Features API when features are managed from an internal tool, provisioning script, or automated setup flow. Send the Server API Key from a trusted backend.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
curl --request POST \
|
|
45
|
+
--url https://api.kelviq.com/api/v1/catalog/features/ \
|
|
46
|
+
--header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
|
|
47
|
+
--header "Content-Type: application/json" \
|
|
48
|
+
--data '{
|
|
49
|
+
"name": "API Calls",
|
|
50
|
+
"identifier": "api-calls",
|
|
51
|
+
"description": "Number of API calls available in a billing period.",
|
|
52
|
+
"featureType": "METER",
|
|
53
|
+
"featureDetails": {
|
|
54
|
+
"featureSubType": "PRE_AGGREGATED_USAGE",
|
|
55
|
+
"units": {
|
|
56
|
+
"singular": "call",
|
|
57
|
+
"plural": "calls"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}'
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Use `https://sandboxapi.kelviq.com/api/v1/catalog/features/` with a sandbox Server API Key when testing. Sandbox and production features are separate.
|
|
64
|
+
|
|
65
|
+
### Request fields
|
|
66
|
+
|
|
67
|
+
| Field | Required | Description |
|
|
68
|
+
| --- | --- | --- |
|
|
69
|
+
| `name` | Yes | Readable feature name |
|
|
70
|
+
| `featureType` | Yes | `BOOLEAN`, `METER`, or `CUSTOMIZABLE` |
|
|
71
|
+
| `identifier` | No | Stable code-facing identifier; Kelviq generates one from the name when omitted |
|
|
72
|
+
| `description` | No | Internal explanation of what the feature controls |
|
|
73
|
+
| `featureDetails` | For Meter setup | Meter subtype and units |
|
|
74
|
+
| `meter` | For raw-event meters | Aggregation and filter configuration |
|
|
75
|
+
| `metadata` | No | Additional key-value data for your own workflow |
|
|
76
|
+
|
|
77
|
+
For a Boolean or Customizable feature, the request can be shorter:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"name": "Advanced Analytics",
|
|
82
|
+
"identifier": "advanced-analytics",
|
|
83
|
+
"featureType": "BOOLEAN"
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The API returns `201 Created` with the new feature, including its Kelviq UUID. See the [Create a feature API reference](/api-reference/features/create-a-feature) for the complete request and response schema.
|
|
88
|
+
|
|
89
|
+
## Add the feature to a plan
|
|
90
|
+
|
|
91
|
+
The feature remains independent until you attach it to a plan:
|
|
92
|
+
|
|
93
|
+
1. Open **Product catalog → Products** and select a product.
|
|
94
|
+
2. Open the plan you want to configure.
|
|
95
|
+
3. Go to **Features & limits** and choose **Manage features & limits**.
|
|
96
|
+
4. Search for the feature and add it to the plan.
|
|
97
|
+
5. Configure the entitlement value:
|
|
98
|
+
- Enable or disable a Boolean feature.
|
|
99
|
+
- Enter the allowed value for a Customizable feature.
|
|
100
|
+
- Set the limit, reset cadence, hard-limit behavior, rollover, or alerts for a Meter feature.
|
|
101
|
+
6. Save the plan. Publish the draft when it is ready for customers.
|
|
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.
|
|
104
|
+
|
|
105
|
+
## Common problems
|
|
106
|
+
|
|
107
|
+
| Problem | What to check |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| The feature does not appear for customers | Confirm that it was added to the correct plan and that the plan version was published |
|
|
110
|
+
| Usage reports return a feature error | Send the exact feature identifier, not its display name |
|
|
111
|
+
| A Meter feature cannot be created | Enter both the singular and plural unit names |
|
|
112
|
+
| The feature exists in Sandbox but not Production | Create it separately in the production environment |
|
|
113
|
+
| The identifier or type is wrong | Create a new feature; these fields cannot be changed after creation |
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Create an Enterprise plan"
|
|
3
|
+
slug: "product-catalog/create-an-enterprise-plan"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Set up a reusable Enterprise tier or a bespoke customer deal in Kelviq"
|
|
6
|
+
---
|
|
7
|
+
An Enterprise plan is a plan in your product catalog. It is not created from the customer page and it is not a separate Kelviq resource type.
|
|
8
|
+
|
|
9
|
+
Create the plan under a product first. You can then use it in one of two ways:
|
|
10
|
+
|
|
11
|
+
| What you sell | Recommended setup |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| The same Enterprise package at a published price | Create a paid Enterprise plan, publish it, then generate checkout for the customer from their detail page. |
|
|
14
|
+
| A negotiated price for each customer | Create an Enterprise plan as the access template, choose **Custom** pricing, and create checkout with `customAmount` after the deal is agreed. |
|
|
15
|
+
|
|
16
|
+
Think of the plan as the product and entitlement template. The checkout session holds the price agreed with a specific customer.
|
|
17
|
+
|
|
18
|
+
## Create the plan
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
Go to **Product Catalog → Products** and select the product the Enterprise plan belongs to.
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
Click **+ Create plan** and enter:
|
|
28
|
+
|
|
29
|
+
- **Plan name:** `Enterprise`
|
|
30
|
+
- **Identifier:** `enterprise`
|
|
31
|
+
- **Description:** A short description of the package shown to customers
|
|
32
|
+
|
|
33
|
+
Keep the identifier stable. Your checkout and entitlement integrations use it as `planIdentifier`.
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
Use **Paid** when every Enterprise customer pays one published price. Add the billing periods and currencies you sell.
|
|
39
|
+
|
|
40
|
+
Use **Custom** when the price is negotiated. Pricing tables show the plan as **Custom** with a **Contact Us** action instead of sending the buyer straight to checkout.
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
Add the features, limits, usage allowances, files, license keys, and links included in the Enterprise agreement.
|
|
46
|
+
|
|
47
|
+
For example, the plan might enable SSO and audit logs, allow 100 seats, and include a higher API limit.
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
Review the configuration and click **Publish**. A draft plan cannot be used for a live customer checkout.
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
## Sell a fixed-price Enterprise plan
|
|
56
|
+
|
|
57
|
+
Use the customer detail page when the Enterprise plan already has the correct price.
|
|
58
|
+
|
|
59
|
+
1. Open **Customers** and select the customer.
|
|
60
|
+
2. Click **Add Subscription**.
|
|
61
|
+
3. Select the published Enterprise plan.
|
|
62
|
+
4. Choose its billing period and currency.
|
|
63
|
+
5. Enter quantities for priced features, such as seats, when required.
|
|
64
|
+
6. Enter the URL where Kelviq should send the customer after checkout.
|
|
65
|
+
7. Click **Generate checkout link** and share the link with the customer.
|
|
66
|
+
|
|
67
|
+
The customer must complete checkout. Generating the link does not activate the subscription or prove that payment succeeded.
|
|
68
|
+
|
|
69
|
+
**Add Subscription** selects an existing plan. It does not create an Enterprise plan, and it does not provide a field for a negotiated custom amount.
|
|
70
|
+
|
|
71
|
+
## Sell a bespoke Enterprise deal
|
|
72
|
+
|
|
73
|
+
For negotiated pricing, keep one Enterprise plan as the common access template. Create a checkout session with the amount, currency, tax treatment, customer ID, and billing period agreed in the contract.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
curl --request POST \
|
|
77
|
+
--url https://sandboxapi.kelviq.com/api/v1/checkout/ \
|
|
78
|
+
--header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
|
|
79
|
+
--header "Content-Type: application/json" \
|
|
80
|
+
--data '{
|
|
81
|
+
"planIdentifier": "enterprise",
|
|
82
|
+
"customerId": "acme-123",
|
|
83
|
+
"chargePeriod": "MONTHLY",
|
|
84
|
+
"currencyCode": "USD",
|
|
85
|
+
"customAmount": 349,
|
|
86
|
+
"taxBehavior": "EXCLUSIVE",
|
|
87
|
+
"successUrl": "https://app.example.com/billing/success",
|
|
88
|
+
"discountsEnabled": false,
|
|
89
|
+
"metadata": {
|
|
90
|
+
"dealId": "deal-2026-1042"
|
|
91
|
+
}
|
|
92
|
+
}'
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`customAmount` overrides the plan's standard checkout price for this session. `taxBehavior` is required: use `INCLUSIVE` when tax is already part of the agreed amount, or `EXCLUSIVE` when Kelviq should add tax at checkout. A Server API Key request must also include `currencyCode`.
|
|
96
|
+
|
|
97
|
+
The response contains `checkoutUrl`. Send the customer to that URL to review the amount and complete payment.
|
|
98
|
+
|
|
99
|
+
Create custom checkout sessions on your backend. Never expose a Server API Key in browser code.
|
|
100
|
+
|
|
101
|
+
See the [Checkout configuration guide](/checkout/checkout-configuration#checkout-session-options) and [Create a checkout session API reference](/api-reference/checkout/create-a-checkout-session) for the complete request schema.
|
|
102
|
+
|
|
103
|
+
## Handle the Contact Us action
|
|
104
|
+
|
|
105
|
+
If you use Kelviq's React pricing table, route custom-plan clicks to your sales form or booking page:
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
<KQPricingTable
|
|
109
|
+
onCustomPriceClick={({ plan }) => {
|
|
110
|
+
window.location.assign(`/contact-sales?plan=${plan.identifier}`);
|
|
111
|
+
}}
|
|
112
|
+
/>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
This starts the sales conversation. After you agree on price and terms, create the customer record and custom checkout session from your backend.
|
|
116
|
+
|
|
117
|
+
[Read the React UI custom-price documentation →](/frontend-integration/react-ui#72-custom-price-plans)
|
|
118
|
+
|
|
119
|
+
## Customer-specific access
|
|
120
|
+
|
|
121
|
+
You do not need a new catalog plan for every small exception. After the customer buys the Enterprise plan, open their detail page and override a feature value or usage limit for that customer.
|
|
122
|
+
|
|
123
|
+
Create a separate plan when the package itself is meaningfully different and you expect to reuse or report on it as a distinct offering. Use customer overrides for one-off limits such as extra seats, API calls, or storage.
|
|
124
|
+
|
|
125
|
+
## Check the setup before sharing checkout
|
|
126
|
+
|
|
127
|
+
- The plan is published in the same environment as the customer and API key.
|
|
128
|
+
- The `customerId` matches the stable ID from your application.
|
|
129
|
+
- The billing period, currency, and custom amount match the signed quote.
|
|
130
|
+
- The tax behavior matches how the price was presented.
|
|
131
|
+
- The plan contains the promised features, limits, and deliverables.
|
|
132
|
+
|
|
133
|
+
Test the flow in sandbox first. After payment, confirm the order and subscription in Kelviq, then check the customer's entitlements before granting access in your application.
|
|
@@ -6,9 +6,14 @@ description: "Create coupons and promotional codes"
|
|
|
6
6
|
---
|
|
7
7
|
You can manage all your coupons from the **Product Catalog**.
|
|
8
8
|
|
|
9
|
-
Navigate to **Product Catalog > Discounts** to see a list of every active and expired code.
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
Navigate to **Product Catalog > Discounts** to see a list of every active and expired code.
|
|
10
|
+
|
|
11
|
+
You can create two types of discounts:
|
|
12
|
+
|
|
13
|
+
* **Percentage** — Reduces an eligible price by a percentage, such as 20%.
|
|
14
|
+
* **Fixed amount** — Subtracts a specific amount in a selected currency, such as USD 10 or INR 500.
|
|
15
|
+
|
|
16
|
+
For a fixed-amount discount, select the currency next to the amount. Kelviq places the currency from your organization profile first in the list, but you should still review the selection before creating the discount.
|
|
12
17
|
|
|
13
18
|
## Create a discount
|
|
14
19
|
|
|
@@ -41,10 +46,11 @@ Navigate to **Product Catalog > Discounts** to see a list of every active and ex
|
|
|
41
46
|
You can control exactly how and when a discount applies.
|
|
42
47
|
|
|
43
48
|
### Duration
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
*
|
|
47
|
-
* **
|
|
49
|
+
Recurring discount settings are enabled by default. Choose how long the discount should apply:
|
|
50
|
+
|
|
51
|
+
* Enter a number of billing cycles for a limited recurring discount.
|
|
52
|
+
* Select **Discount applies forever** to apply it to every eligible recurring invoice.
|
|
53
|
+
* Turn off **Recurring discount** when the code should apply only to the initial purchase.
|
|
48
54
|
|
|
49
55
|
### Usage & expiry
|
|
50
56
|
Control the scarcity of the coupon.
|
|
@@ -52,12 +58,19 @@ Control the scarcity of the coupon.
|
|
|
52
58
|
* **Expiry date:** Set a hard deadline when the code stops working.
|
|
53
59
|
|
|
54
60
|
### Product restrictions
|
|
55
|
-
By default, a discount applies to
|
|
61
|
+
By default, a discount applies to the entire catalog. To restrict it:
|
|
62
|
+
|
|
63
|
+
1. Enable **Limit discount to selected products**.
|
|
64
|
+
2. Select a product in every restriction row you add.
|
|
65
|
+
3. Optionally select a specific plan price. Choose **Applies to all plans** to include every price under that product.
|
|
66
|
+
|
|
67
|
+
Kelviq will not create the discount while a restriction row has no product selected.
|
|
68
|
+
|
|
69
|
+
For fixed-amount discounts, the discount currency must match the currency of the selected price. Kelviq shows a validation error when the currencies do not match.
|
|
70
|
+
|
|
71
|
+
## Apply a discount at checkout
|
|
56
72
|
|
|
57
|
-
|
|
58
|
-
2. Select the products you want to include.
|
|
59
|
-
3. **Refine scope:** You can go even deeper by selecting specific price points.
|
|
60
|
-
* *Example:* Apply the discount only to the "Pro Plan - Yearly" interval, while excluding the "Monthly" version.
|
|
73
|
+
Customers can enter a code themselves, or you can pre-apply one through the Checkout API or a static checkout link. See [Apply a discount code at checkout](/checkout/apply-a-discount-code) for working examples and field names.
|
|
61
74
|
|
|
62
75
|
## Management
|
|
63
76
|
|
|
@@ -92,6 +92,32 @@ You don't need to:
|
|
|
92
92
|
|
|
93
93
|
---
|
|
94
94
|
|
|
95
|
+
## When the Entitlement API is unavailable
|
|
96
|
+
|
|
97
|
+
Kelviq serves entitlement checks through its edge API. The service targets P95 response times below 100 ms and an uptime SLA above 99.99%, but your access-control path should still account for a temporary network or API failure.
|
|
98
|
+
|
|
99
|
+
### Node and Python SDK fallback
|
|
100
|
+
|
|
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.
|
|
102
|
+
|
|
103
|
+
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
|
+
|
|
105
|
+
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
|
+
|
|
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.
|
|
108
|
+
|
|
109
|
+
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
|
+
|
|
111
|
+
### Calling the API directly
|
|
112
|
+
|
|
113
|
+
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
|
+
|
|
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.
|
|
116
|
+
|
|
117
|
+
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
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
95
121
|
## Feature Types
|
|
96
122
|
|
|
97
123
|
Kelviq supports three types of features to cover all access control scenarios.
|
|
@@ -218,7 +244,7 @@ For complete checkout API options, see the [Node SDK Documentation](https://docs
|
|
|
218
244
|
| **New customer ID** | Customer created automatically, entitlements assigned |
|
|
219
245
|
| **Existing customer** | Entitlements updated based on new purchase |
|
|
220
246
|
| **Upgrade** | New plan entitlements replace old ones |
|
|
221
|
-
| **Downgrade** |
|
|
247
|
+
| **Downgrade** | New plan entitlements replace old ones immediately |
|
|
222
248
|
|
|
223
249
|
### Automatic Assignment
|
|
224
250
|
|
|
@@ -248,8 +274,9 @@ yarn add @kelviq/node-sdk
|
|
|
248
274
|
```javascript
|
|
249
275
|
import { Kelviq } from '@kelviq/node-sdk';
|
|
250
276
|
|
|
251
|
-
const client = new Kelviq({
|
|
252
|
-
accessToken: process.env.
|
|
277
|
+
const client = new Kelviq({
|
|
278
|
+
accessToken: process.env.KELVIQ_SERVER_API_KEY,
|
|
279
|
+
environment: process.env.KELVIQ_ENV, // 'sandbox' or 'production'
|
|
253
280
|
});
|
|
254
281
|
```
|
|
255
282
|
|
|
@@ -301,6 +328,18 @@ The sandbox environment is completely separate from production. Use different AP
|
|
|
301
328
|
|
|
302
329
|
---
|
|
303
330
|
|
|
331
|
+
## Manage feature definitions
|
|
332
|
+
|
|
333
|
+
Open **Product Catalog → Features** to create and manage reusable feature definitions. See [Create a feature in Kelviq](/product-catalog/create-a-feature) for the complete dashboard and API workflows.
|
|
334
|
+
|
|
335
|
+
* Use the row action menu to edit a feature name.
|
|
336
|
+
* Metered values, percentages, and rollover limits use numeric inputs.
|
|
337
|
+
* When configuring a metered entitlement, set the usage reset and hard-limit behavior first, then configure credit rollover and usage alerts.
|
|
338
|
+
|
|
339
|
+
When adding features to a plan from **Manage features & limits**, search for a feature and click **Add**. Kelviq clears the search after the feature is added so you can search for the next feature immediately.
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
304
343
|
## Managing Customer Entitlements
|
|
305
344
|
|
|
306
345
|
### Viewing Customer Entitlements
|
|
@@ -401,27 +440,25 @@ When you set up inheritance:
|
|
|
401
440
|
#### Upgrade
|
|
402
441
|
- New plan entitlements replace old ones
|
|
403
442
|
- Happens immediately
|
|
404
|
-
-
|
|
443
|
+
- Existing usage counters are retained and evaluated against the new limits
|
|
405
444
|
|
|
406
445
|
#### Downgrade
|
|
407
|
-
- New entitlements
|
|
408
|
-
-
|
|
409
|
-
-
|
|
446
|
+
- New plan entitlements replace old ones immediately
|
|
447
|
+
- Existing usage counters are retained
|
|
448
|
+
- A customer can become over limit when the new limit is below current usage
|
|
410
449
|
|
|
411
450
|
#### Cancellation
|
|
412
|
-
-
|
|
413
|
-
-
|
|
414
|
-
- Access revoked when subscription expires
|
|
451
|
+
- Immediate cancellation revokes plan access immediately
|
|
452
|
+
- Period-end cancellation keeps entitlements active until the subscription expires
|
|
415
453
|
|
|
416
454
|
#### Failed Payment
|
|
417
|
-
-
|
|
418
|
-
-
|
|
419
|
-
-
|
|
420
|
-
- Entitlements restored when payment succeeds
|
|
455
|
+
- A failed card renewal moves the subscription to `past_due`
|
|
456
|
+
- Kelviq retries card payments for up to 14 days before cancellation
|
|
457
|
+
- Failed non-card renewals are not retried and the subscription is cancelled
|
|
421
458
|
|
|
422
459
|
#### Refund
|
|
423
|
-
-
|
|
424
|
-
-
|
|
460
|
+
- Cancelling mid-period does not automatically create a refund
|
|
461
|
+
- The merchant decides whether to issue a full, partial, or no refund
|
|
425
462
|
|
|
426
463
|
Manage subscriptions programmatically using the [Subscriptions API](https://docs.kelviq.com/backend-integration/node-sdk#subscriptions).
|
|
427
464
|
|
|
@@ -24,12 +24,16 @@ Users who select this plan bypass the payment step entirely. They still get acce
|
|
|
24
24
|
|
|
25
25
|
Free trials let customers test a paid plan for a specific number of days before their card is charged.
|
|
26
26
|
|
|
27
|
+
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.
|
|
28
|
+
|
|
27
29
|
<img height="200" src="/images/billing-cycle.png" />
|
|
28
30
|
|
|
29
|
-
1. Open a paid plan draft
|
|
30
|
-
2.
|
|
31
|
-
3. Enable
|
|
32
|
-
4. Enter the number of days the trial should last
|
|
31
|
+
1. Open a paid plan draft.
|
|
32
|
+
2. Enable at least one recurring billing cycle, such as **28 days**, **Monthly**, or **Yearly**.
|
|
33
|
+
3. Enable **Free trial**.
|
|
34
|
+
4. Enter the number of days the trial should last.
|
|
35
|
+
|
|
36
|
+
If you later disable the final recurring billing cycle and leave only one-time pricing, Kelviq removes the trial from the one-time offer.
|
|
33
37
|
|
|
34
38
|
When a customer signs up they must enter a valid payment method. We authorize the card but do not charge it. When the trial period ends Kelviq automatically charges the card and begins the regular billing cycle.
|
|
35
39
|
|
|
@@ -10,6 +10,8 @@ Location based pricing is a feature that allows you to set custom prices for spe
|
|
|
10
10
|
|
|
11
11
|
To offer a localized price open your plan configuration and expand the Price localization card.
|
|
12
12
|
|
|
13
|
+
Regional prices inherit the base price's usage reset, usage alert, and credit rollover settings. Regional pricing changes the localized monetary price; it does not create a separate usage-policy configuration.
|
|
14
|
+
|
|
13
15
|
### 1. Choose a currency
|
|
14
16
|
|
|
15
17
|
Select your target currency from the dropdown list. You can choose options like Euro or Indian Rupee. Click Add localized price to open the configuration panel.
|
|
@@ -15,8 +15,12 @@ Not every product needs a subscription. If you are selling a lifetime software l
|
|
|
15
15
|
3. Enter the total amount you want to charge
|
|
16
16
|
4. Click Save
|
|
17
17
|
|
|
18
|
+
One-time payments do not support free trials. To offer a trial, add and enable a recurring billing cycle on the plan.
|
|
19
|
+
|
|
18
20
|
Customers pay this amount exactly once during checkout. If you attach digital downloads or license keys to this plan they gain permanent access to those assets immediately after payment.
|
|
19
21
|
|
|
22
|
+
If an existing customer already has a saved payment method, you can also [create a one-time charge from your backend](/sales/create-a-one-time-charge) without sending them through checkout again.
|
|
23
|
+
|
|
20
24
|
## Combine with usage
|
|
21
25
|
|
|
22
26
|
You can charge a one time setup fee and still bill for ongoing usage.
|