@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.
Files changed (63) hide show
  1. package/README.md +34 -26
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +23 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +114 -34
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +102 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/server.js +10 -1
  62. package/dist/server.js.map +1 -1
  63. 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 provides a granular breakdown of every single movement of money. This includes successful payments, refunds, and failures.
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
- You can filter the list to find specific issues.
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
- * **Gross total:** The amount the customer paid.
21
- * **Processing fees:** The platform and gateway fees deducted.
22
- * **Net earnings:** The final amount added to your balance.
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 &#36;5,000 in total volume | 2.9% + &#36;0.40 | Transactions processed before your organization reaches &#36;5,000 in cumulative sales |
45
+ | Base fee after &#36;5,000 in total volume | 3.5% + &#36;0.40 | Subsequent transactions after your organization reaches &#36;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 &#36;5,000 threshold is charged 5.7% + &#36;0.40: 3.5% base, 0.7% recurring, and 1.5% international.
50
+
51
+ ### Example from the transaction list
52
+
53
+ For a &#36;57.60 domestic, one-time payment processed after the &#36;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 &#36;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. You can create two types of discounts:
10
- * **Percentage:** A relative cut (e.g. 20% off).
11
- * **Fixed amount:** A specific dollar value (e.g. $10 off).
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
- For recurring subscriptions, you define how long the discount lasts.
45
- * **Once:** Applies only to the first invoice.
46
- * **Forever:** Applies to every invoice indefinitely.
47
- * **Repeating:** Applies for a specific number of billing cycles (e.g. "3 months off").
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 your entire catalog. You can restrict it to specific items.
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
- 1. Toggle **Limit discount on selected products**.
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** | Adjusted at end of current billing period |
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.KELVIQ_ACCESS_TOKEN
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
- - Usage meters may reset or carry over (configurable)
443
+ - Existing usage counters are retained and evaluated against the new limits
405
444
 
406
445
  #### Downgrade
407
- - New entitlements take effect at end of billing period
408
- - Customer keeps current access until then
409
- - Prevents mid-cycle disruption
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
- - Entitlements remain active until period ends
413
- - Customer can use features they paid for
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
- - Grace period begins (configurable)
418
- - Customer retains access during grace period
419
- - After grace period: access revoked
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
- - Entitlements revoked immediately
424
- - Customer loses access to plan features
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. Select your billing cycles like monthly or yearly
31
- 3. Enable the Free trial toggle
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.