@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.
Files changed (101) hide show
  1. package/README.md +40 -3
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +1 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/ai/docs-for-agents.md +21 -0
  6. package/dist/docs/ai/overview.md +43 -0
  7. package/dist/docs/api-reference/authentication.md +9 -3
  8. package/dist/docs/api-reference/introduction.md +23 -2
  9. package/dist/docs/backend-integration/node-sdk.md +12 -6
  10. package/dist/docs/backend-integration/python-sdk.md +14 -8
  11. package/dist/docs/changelog.md +352 -3
  12. package/dist/docs/checkout/checkout-configuration.md +25 -75
  13. package/dist/docs/checkout/checkout-design.md +76 -0
  14. package/dist/docs/checkout/checkout-examples.md +212 -0
  15. package/dist/docs/checkout/checkout-metadata.md +1 -1
  16. package/dist/docs/checkout/custom-fields.md +60 -0
  17. package/dist/docs/checkout/embed-checkout.md +280 -0
  18. package/dist/docs/checkout/payment-methods/upi.md +69 -0
  19. package/dist/docs/checkout/payment-methods.md +119 -0
  20. package/dist/docs/checkout/static-checkout-url.md +3 -2
  21. package/dist/docs/cli/commands.md +57 -4
  22. package/dist/docs/cli/kelviq-config.md +1 -1
  23. package/dist/docs/cli/overview.md +1 -0
  24. package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
  25. package/dist/docs/customer-portal/overview.md +7 -7
  26. package/dist/docs/customer-portal/retention.md +109 -0
  27. package/dist/docs/customers-management/overview.md +105 -0
  28. package/dist/docs/frontend-integration/js-sdk.md +11 -11
  29. package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
  30. package/dist/docs/frontend-integration/react-sdk.md +8 -49
  31. package/dist/docs/frontend-integration/react-ui.md +8 -6
  32. package/dist/docs/getstarted/fees.md +27 -11
  33. package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
  34. package/dist/docs/getstarted/merchant-of-record.md +18 -24
  35. package/dist/docs/getstarted/overview.md +98 -0
  36. package/dist/docs/getstarted/review-process.md +59 -59
  37. package/dist/docs/guides/agent-toolkit.md +14 -9
  38. package/dist/docs/guides/mcp-server.md +24 -9
  39. package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
  40. package/dist/docs/guides/sandbox.md +6 -4
  41. package/dist/docs/guides/set-up-with-ai.md +43 -0
  42. package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
  43. package/dist/docs/guides/subscription-integration.md +1 -1
  44. package/dist/docs/guides/test-payments.md +640 -0
  45. package/dist/docs/guides/webhooks.md +182 -30
  46. package/dist/docs/integrations/woocommerce.md +88 -0
  47. package/dist/docs/integrations/zapier.md +22 -0
  48. package/dist/docs/legal/account-and-funds.md +59 -0
  49. package/dist/docs/legal/approved-prohibited-policy.md +32 -27
  50. package/dist/docs/legal/payment-flow-diagram.md +7 -7
  51. package/dist/docs/manifest.json +160 -41
  52. package/dist/docs/openapi.json +1359 -109
  53. package/dist/docs/payouts/overview.md +14 -12
  54. package/dist/docs/payouts/payout-account.md +1 -1
  55. package/dist/docs/payouts/transactions.md +3 -3
  56. package/dist/docs/product-catalog/create-a-feature.md +3 -3
  57. package/dist/docs/product-catalog/digital-downloads.md +5 -5
  58. package/dist/docs/product-catalog/discounts.md +2 -2
  59. package/dist/docs/product-catalog/entitlements.md +20 -27
  60. package/dist/docs/product-catalog/free-and-trials.md +4 -4
  61. package/dist/docs/product-catalog/license-keys.md +56 -29
  62. package/dist/docs/product-catalog/links.md +3 -3
  63. package/dist/docs/product-catalog/location-based-pricing.md +6 -10
  64. package/dist/docs/product-catalog/one-time-payments.md +3 -7
  65. package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
  66. package/dist/docs/product-catalog/plans.md +22 -19
  67. package/dist/docs/product-catalog/products.md +11 -3
  68. package/dist/docs/product-catalog/proration.md +69 -0
  69. package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
  70. package/dist/docs/product-catalog/subscriptions.md +52 -22
  71. package/dist/docs/product-catalog/tax-settings.md +8 -8
  72. package/dist/docs/product-catalog/usage-alerts.md +7 -7
  73. package/dist/docs/product-catalog/usage-based-billing.md +156 -29
  74. package/dist/docs/product-catalog/usage-limits.md +78 -0
  75. package/dist/docs/promotions/create-a-promotion.md +2 -2
  76. package/dist/docs/promotions/overview.md +1 -1
  77. package/dist/docs/quickstart/core-concepts.md +36 -30
  78. package/dist/docs/quickstart/dashboard-setup.md +26 -22
  79. package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
  80. package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
  81. package/dist/docs/sales/checkout-sessions.md +28 -39
  82. package/dist/docs/sales/orders.md +30 -54
  83. package/dist/docs/settings/customer-emails.md +52 -0
  84. package/dist/docs/settings/members.md +27 -0
  85. package/dist/docs/settings/profile.md +26 -0
  86. package/dist/docs/settings/zapier.md +22 -0
  87. package/dist/http/errors.d.ts +20 -1
  88. package/dist/http/errors.js +83 -31
  89. package/dist/http/errors.js.map +1 -1
  90. package/dist/schemas/kelviq.d.ts +54 -0
  91. package/dist/schemas/kelviq.js +64 -0
  92. package/dist/schemas/kelviq.js.map +1 -1
  93. package/dist/server.js +3 -2
  94. package/dist/server.js.map +1 -1
  95. package/dist/tools/imports.d.ts +68 -0
  96. package/dist/tools/imports.js +242 -0
  97. package/dist/tools/imports.js.map +1 -0
  98. package/dist/tools/index.d.ts +2 -1
  99. package/dist/tools/index.js +4 -1
  100. package/dist/tools/index.js.map +1 -1
  101. package/package.json +1 -1
@@ -4,7 +4,7 @@ slug: "frontend-integration/react-sdk"
4
4
  section: "frontend-integration"
5
5
  description: "Documentation for the Kelviq React SDK"
6
6
  ---
7
- The `@kelviq/react-sdk` provides a seamless way to integrate kelviq entitlement management into your React applications.
7
+ The `@kelviq/react-sdk` provides a seamless way to integrate Kelviq entitlement management into your React applications.
8
8
 
9
9
  ## Overview
10
10
 
@@ -84,7 +84,7 @@ export default App;
84
84
  - `plansEnabled?: string`
85
85
  - Comma-separated list of plan identifiers to include in the pricing response. When omitted, all active plans for the product are returned. Example: `"pro,enterprise"`.
86
86
  - `apiUrl: string`
87
- - The base URL for your kelviq API. For example, `https://edge.api.kelviq.com/api/v1`.
87
+ - The base URL for your Kelviq API. For example, `https://edge.api.kelviq.com/api/v1`.
88
88
  - `environment: 'sandbox' | 'production'`
89
89
  - The environment to use. If you want to use the sandbox, you must provide this.
90
90
  - `entitlementsPath: string`
@@ -99,11 +99,11 @@ This optional object can contain the following properties:
99
99
  - `onError?: (error: Error) => void`
100
100
  - A callback function that will be invoked if an error occurs during the API request for entitlements.
101
101
  - `maxRetries?: number`
102
- - The maximum number of times to retry a failed API request. Defaults to the value set in your `apiRequest` service (typically 3).
102
+ - The maximum number of times to retry a failed API request. Defaults to `3`.
103
103
  - `timeout?: number`
104
- - Timeout for API requests in milliseconds. Defaults to the value set in your `apiRequest` service (typically 5000ms).
104
+ - Timeout for API requests in milliseconds. Defaults to `5000`.
105
105
  - `backoffBaseDelay?: number`
106
- - Base delay (in milliseconds) for the exponential backoff strategy used in retries. Defaults to the value set in your `apiRequest` service (typically 1000ms).
106
+ - Base delay (in milliseconds) for the exponential backoff strategy used in retries. Defaults to `1000`.
107
107
  - `fetchEntitlementsOnMount?: boolean`
108
108
  - Defaults to `true`. If true, entitlements are fetched automatically when the `KelviqProvider` mounts.
109
109
  - Set to `false` if you want to control the initial fetch manually using the `refreshAllEntitlements` function from the `useKelviq` hook.
@@ -600,10 +600,10 @@ const entitlement = useCustomizableEntitlement("max-items-per-page");
600
600
 
601
601
  ### `useMeteredEntitlement(featureId: string)`
602
602
 
603
- Returns the aggregated entitlement for a specific metered feature from the cache.
603
+ Returns the aggregated entitlement for a specific Meter feature from the cache.
604
604
 
605
605
  - **Arguments:**
606
- - `featureId: string`: The identifier of the metered feature.
606
+ - `featureId: string`: The identifier of the Meter feature.
607
607
  - **Returns:** `Entitlement | null`
608
608
 
609
609
  ```tsx
@@ -921,7 +921,7 @@ import { ShowWhenCustomizableEntitled } from '@kelviq/react-sdk';
921
921
 
922
922
  ### `ShowWhenMeteredEntitled`
923
923
 
924
- Renders children if the metered feature is enabled and, by default, if `remaining` usage is greater than 0 or unlimited (`usageLimit` is `null`).
924
+ Renders children if the Meter feature is enabled and, by default, if `remaining` usage is greater than 0 or unlimited (`usageLimit` is `null`).
925
925
 
926
926
  - **Optional Prop:**
927
927
  - `condition?: (data: Entitlement) => boolean`: A custom function to further determine if children should render based on the entitlement data.
@@ -1132,47 +1132,6 @@ A comprehensive example is provided within the comments of the SDK code, demonst
1132
1132
  1. Wrapping your application with `KelviqProvider` and providing the required props (`customerId`, `accessToken`)
1133
1133
  2. Using hooks like `useBooleanEntitlement` or conditional components like `ShowWhenBooleanEntitled` in your components to control UI and behavior based on entitlements.
1134
1134
 
1135
- ## **11. API Request Service**
1136
-
1137
- The SDK relies on an `apiRequest` function for making HTTP requests. The SDK's `KelviqProvider` passes configuration like `timeout`, `maxRetries`, `backoffBaseDelay`, and `accessToken` to this function.
1138
-
1139
- - **Your Responsibility:** You need to ensure that your project includes an implementation of this `apiRequest` service (e.g., in `src/services/makeRequest.service.ts`) that matches the `ApiRequestConfig` and `ApiResponse` interfaces used by the SDK. This service should handle actual HTTP communication, including appending query parameters passed via `ApiRequestConfig.queryParams` and using the `accessToken` to set the `Authorization` header.
1140
- - The placeholder `apiRequest` function included in the SDK's source code is for demonstration and type-checking purposes only and will not make real API calls.
1141
-
1142
- ## **12. Project Structure (for contributors/reference)**
1143
-
1144
- The SDK source code (`lib/`) is organized as follows:
1145
-
1146
- - `components/`: Contains conditional rendering and pricing React components.
1147
- - `ShowWhenBooleanEntitled.tsx`
1148
- - `ShowWhenCustomizableEntitled.tsx`
1149
- - `ShowWhenMeteredEntitled.tsx`
1150
- - `ShowWhenEntitledInternal.tsx` (Internal helper, not typically exported)
1151
- - `KQPrice.tsx`
1152
- - `KQFeatureList.tsx`
1153
- - `contexts/`: Defines the React Context and Provider.
1154
- - `KelviqContext.ts`
1155
- - `KelviqProvider.tsx`
1156
- - `hooks/`: Contains all custom React Hooks.
1157
- - `useKelviq.ts`
1158
- - `useAllEntitlements.ts`
1159
- - `useBooleanEntitlement.ts`
1160
- - `useCustomizableEntitlement.ts`
1161
- - `useMeteredEntitlement.ts`
1162
- - `useSubscriptions.ts`
1163
- - `useCustomer.ts`
1164
- - `usePricing.ts`
1165
- - `index.ts` (Exports all hooks)
1166
- - `types/`: Contains all TypeScript definitions.
1167
- - `api.types.ts` (Raw types from API, including pricing types)
1168
- - `sdk.types.ts` (Processed types for SDK and public use)
1169
- - `index.ts` (Re-exports all types)
1170
- - `utils/`: Contains utility functions.
1171
- - `transformations.ts` (For `transformApiEntitlements`)
1172
- - `formatPrice.ts` (For `kqFormatPrice`)
1173
- - `index.ts` (Exports utilities)
1174
- - `index.ts`: The main entry point of the SDK, re-exporting all public APIs (provider, hooks, components, types).
1175
-
1176
1135
  ## Using the Sandbox
1177
1136
 
1178
1137
  If you want to use the sandbox, you need to set the `environment` option to `sandbox` in the `KelviqProvider`.
@@ -2,11 +2,11 @@
2
2
  title: "React UI"
3
3
  slug: "frontend-integration/react-ui"
4
4
  section: "frontend-integration"
5
- description: "Documentation for the kelviq React UI SDK - A comprehensive pricing table and paywall solution"
5
+ description: "Documentation for the Kelviq React UI SDK - A comprehensive pricing table and paywall solution"
6
6
  ---
7
7
  ## 1. Overview
8
8
 
9
- The **kelviq React UI SDK** provides a complete React-based solution for integrating dynamic, customizable pricing tables and paywalls into web applications. It handles fetching offering data, displaying pricing plans with multiple billing periods, managing subscriptions, and processing checkouts with full localization support.
9
+ The **Kelviq React UI SDK** provides a complete React-based solution for integrating dynamic, customizable pricing tables and paywalls into web applications. It handles fetching offering data, displaying pricing plans with multiple billing periods, managing subscriptions, and processing checkouts with full localization support.
10
10
 
11
11
  ---
12
12
 
@@ -45,6 +45,8 @@ function App() {
45
45
  }
46
46
  ```
47
47
 
48
+ `accessToken` is your **Client API Key** from the [API keys](https://app.kelviq.com/settings/api-keys) section of the Kelviq dashboard. It is safe to use in the browser. See [`KelviqProvider`](#4-1-kelviqprovider) for the full list of props.
49
+
48
50
  ### With Custom Event Handling
49
51
 
50
52
  ```tsx
@@ -81,7 +83,7 @@ The top-level provider component that initializes the SDK and manages the global
81
83
 
82
84
  | Prop | Type | Description |
83
85
  |------|------|-------------|
84
- | `accessToken` | `string` | Your kelviq access token |
86
+ | `accessToken` | `string` | Your Kelviq access token |
85
87
  | `productId` | `string` | The unique identifier of the product to display the offering for |
86
88
 
87
89
  #### Optional Props
@@ -256,7 +258,7 @@ Renders the features list for a plan.
256
258
  | `customTooltipIcon` | `React.ReactNode` | No | Custom tooltip icon |
257
259
  | `onUsageChange` | `(featureId: string, quantity: number) => void` | No | Usage change handler |
258
260
 
259
- > Feature tooltips are controlled per-feature by the `displayTooltipDescription` flag on each feature in the offering data, configured in your kelviq dashboard — there is no global tooltip prop.
261
+ > Feature tooltips are controlled per-feature by the `displayTooltipDescription` flag on each feature in the offering data, configured in your Kelviq dashboard — there is no global tooltip prop.
260
262
 
261
263
  ---
262
264
 
@@ -539,7 +541,7 @@ For complete styling control, use the `noStyles` prop:
539
541
 
540
542
  ### 6.6. CSS Class Reference
541
543
 
542
- The kelviq React UI components use consistent CSS class names that you can target for custom styling. All classes are prefixed with `kq-` to avoid naming conflicts.
544
+ The Kelviq React UI components use consistent CSS class names that you can target for custom styling. All classes are prefixed with `kq-` to avoid naming conflicts.
543
545
 
544
546
  #### CSS Class Hierarchy
545
547
 
@@ -801,6 +803,6 @@ If you want to use the sandbox, you need to set the `environment` option to `san
801
803
  For technical support and questions:
802
804
 
803
805
  - **Documentation**: [docs.kelviq.com](https://docs.kelviq.com)
804
- - **Email**: support@kelviq.com
806
+ - **Email**: hi@kelviq.com
805
807
 
806
808
  ---
@@ -38,7 +38,7 @@ Every successful payment starts with a base fee. The base rate changes after you
38
38
 
39
39
  The threshold is based on your organization's cumulative processed sales volume, not the number of payments or the volume for a single month. You pay 2.9% + $0.40 on transactions processed before reaching $5,000. After your total processed volume reaches $5,000, subsequent transactions use the 3.5% + $0.40 base rate.
40
40
 
41
- The rate change does not alter fees on transactions that were already processed.
41
+ Fees on earlier transactions stay as they were.
42
42
 
43
43
  ## All fee combinations
44
44
 
@@ -62,6 +62,20 @@ This example uses a $100 gross charge. If the payment includes tax, the gros
62
62
  | Subscription, domestic card | $4.00 | $4.60 |
63
63
  | Subscription, international card | $5.50 | $6.10 |
64
64
 
65
+ ### Example: a sale with sales tax
66
+
67
+ A customer in the US buys a $50 product with a US card. Sales tax is 8%, so they pay $54. Your organization has already passed $5,000 in sales, so the base fee is 3.5% + $0.40. The fee is charged on the full amount the customer pays, including tax.
68
+
69
+ | | Amount |
70
+ | --- | ---: |
71
+ | Customer pays ($50 + $4 sales tax) | $54.00 |
72
+ | Kelviq fee (3.5% of $54 + $0.40) | −$2.29 |
73
+ | Sales tax, collected and remitted by Kelviq | −$4.00 |
74
+ | **Added to your balance** | **$47.71** |
75
+ | Payout fee | $0.00 |
76
+
77
+ Before the $5,000 threshold, the same sale costs 2.9% + $0.40, a $1.97 fee.
78
+
65
79
  ## How fees appear in Transactions
66
80
 
67
81
  The **Fee** column under **Payouts → Transactions** shows the total fee deducted from a payment. It combines the applicable base rate, recurring fee, and international-card fee into one amount. Tax is shown separately.
@@ -76,26 +90,28 @@ Net = Gross - Fee - Tax
76
90
 
77
91
  ## Payout fees
78
92
 
79
- Currently, Kelviq is bearing the payout fee.
80
-
81
- Transaction fees and payout fees happen at different stages. The transaction fee is deducted when a customer pays. A payout fee would typically apply later when funds are sent to your bank account or eligible debit card, but Kelviq currently covers this cost.
93
+ There's no payout fee. Your full 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.
82
94
 
83
95
  [Learn how Kelviq payouts work →](/payouts/overview)
84
96
 
85
97
  ## Refunds
86
98
 
87
- When you issue a refund to a customer, the original transaction fee is **retained**. This applies to both full and partial refunds.
99
+ The transaction fee isn't returned on a refund. Here's how a refund of the $54 sale above is paid out:
100
+
101
+ | | Full refund | Partial refund of $20 |
102
+ | --- | ---: | ---: |
103
+ | Customer gets back | $54.00 | $20.00 |
104
+ | Tax part of the refund, returned by Kelviq | $4.00 | $1.48 |
105
+ | Taken from your balance | $50.00 | $18.52 |
106
+ | **What you keep from the sale** | **−$2.29** | **$29.19** |
88
107
 
89
- | Scenario | What happens |
90
- |----------|--------------|
91
- | Full refund | Customer receives full amount; original fee retained |
92
- | Partial refund | Customer receives partial amount; proportional fee retained |
108
+ For a partial refund, the amount you enter is what the customer gets back, and the tax inside it is worked out proportionally ($20 × $4 / $54 = $1.48).
93
109
 
94
- Our payment partners charge non-refundable processing fees on the original transaction. We pass this cost structure through to maintain transparent pricing.
110
+ Refunds always go through for the customer. If your balance is smaller than the refund, it shows a negative amount.
95
111
 
96
112
  ## Disputes and chargebacks
97
113
 
98
- When a customer disputes a charge with their bank, a **$15 fee** applies regardless of the dispute outcome.
114
+ Each dispute costs a **$15 fee**, whatever the outcome. If you win, the payment stays with you. If the bank sides with the customer, the amount is returned to them.
99
115
 
100
116
  | Outcome | Fee | Transaction amount |
101
117
  |---------|-----|-------------------|
@@ -1,80 +1,43 @@
1
1
  ---
2
- title: "Introduction to kelviq"
2
+ title: "Introduction to Kelviq"
3
3
  slug: "getstarted/introduction-to-kelviq"
4
4
  section: "getstarted"
5
+ description: "What Kelviq does, how it fits into your app, and where to start."
5
6
  ---
6
- ##### Kelviq is the complete monetization platform for your SaaS, AI agents, and digital products. It combines a merchant of record, subscription management, and usage-based billing into one system so you can set prices, track variable compute costs, collect payments, and stay compliant with global tax.
7
+ Kelviq is a merchant of record with billing built in. You set your prices and plans, Kelviq sells them, collects the tax, and pays you out. Your app asks Kelviq what each customer can use.
7
8
 
8
- ---
9
-
10
- ## Why Kelviq
11
-
12
- Monetization is more than just a payment. It's a complex system of pricing models, usage metering, subscription logic, feature access, global tax, and compliance. Building this from scratch takes months of engineering time and ongoing legal overhead.
13
-
14
- Kelviq is the complete revenue system that handles all this complexity for you. You can launch any pricing model and sell globally from day one, all while staying compliant.
15
-
16
- With Kelviq you can:
17
-
18
- - **Get started in minutes** You don’t have to handle dozens of webhooks, build a database layer to track customers, manage subscription states, or hardcode feature access. Kelviq provides a single, unified system.
19
-
20
- - **Handle Global Tax & Compliance Automatically** As your Merchant of Record, Kelviq takes on the full liability for global sales tax (VAT, GST, etc.), fraud, and regulatory compliance. You can sell in 100+ countries without ever registering for a foreign tax ID.
21
-
22
- - **Run any pricing model** Flat fee, usage, seats, tiers, volume, credits, pay-as-you-go, overage charges, or hybrids. Configure them in minutes.
9
+ <div className="kq-chips">
10
+ <a className="kq-chip" href="#what-kelviq-handles"><span className="kq-chip-ico" />Will Kelviq work for my product?</a>
11
+ <a className="kq-chip" href="/payouts/overview#do-i-need-a-stripe-account"><span className="kq-chip-ico" />Do I need a Stripe account?</a>
12
+ <a className="kq-chip" href="/getstarted/fees"><span className="kq-chip-ico" />What does Kelviq cost?</a>
13
+ <a className="kq-chip" href="/product-catalog/usage-based-billing"><span className="kq-chip-ico" />Can I charge per token or API call?</a>
14
+ <a className="kq-chip" href="/guides/set-up-with-ai"><span className="kq-chip-ico" />What's the fastest way to integrate Kelviq?</a>
15
+ </div>
23
16
 
24
- - **Sell digital products with ease** Securely deliver files, e-books, or software on purchase and automatically generates license keys right after checkout.
25
-
26
- - **Meter usage in real time** Track every API request, workflow run, background agent task, or LLM token usage as it happens. Set soft or hard caps, pick reset cycles, send alerts, and handle overages with one call.
27
-
28
- - **Control feature access** Define features per plan. Turn them on or off and check access in your app with one SDK call.
29
-
30
- - **Localized pricing by country** Offer country-specific prices in 135+ currencies with VPN, proxy, and fraud protection built in. You can also set up promotions for specific countries.
31
-
32
- - **Ship pricing changes without touching code** A/B test plans, roll out changes, or update pricing in real time without redeploys.
33
-
34
- - **Manage the full customer lifecycle** Handle upgrades, downgrades, migrations, overrides, and grandfathering without writing custom scripts.
35
-
36
- ---
37
- ## How Kelviq is Different
17
+ ## What Kelviq handles
38
18
 
39
- Traditional billing forces you to build complex infrastructure. Kelviq eliminates this overhead entirely.
19
+ | Area | What you get |
20
+ | --- | --- |
21
+ | **Tax and compliance** | Kelviq is the seller of record. We calculate, collect, and file sales tax, VAT, and GST, and handle fraud and chargebacks. |
22
+ | **Checkout** | Hosted checkout with plan picker, trials, discounts, business purchases, and local payment methods. |
23
+ | **Pricing** | Flat, per seat, usage-based, tiered, volume, credits, pay as you go, one-time, or a mix. |
24
+ | **Entitlements** | Turn features on per plan, set usage limits, and check what each customer can access with one SDK call. In the dashboard, these are **Features & limits**. |
25
+ | **Usage** | Report usage as it happens. Kelviq counts it, resets it, and bills overage. |
26
+ | **Subscriptions** | Upgrades, downgrades, proration, and cancellations, plus a customer portal. |
27
+ | **Digital products** | File downloads, license keys, and links delivered after purchase. |
28
+ | **Local pricing** | Prices by country in 135+ currencies. |
40
29
 
41
-
30
+ Pricing changes happen in the dashboard or the CLI, not in your code. Your app checks features, not plan names, so moving a feature between plans needs no deploy.
42
31
 
43
- Stop handling dozens of webhook events to sync subscription state. Query customer data directly from our API—always accurate, always real-time.
44
-
32
+ ## How it fits together
45
33
 
46
-
34
+ 1. Create **products**, **plans**, and **features** in the dashboard or with the CLI.
35
+ 2. Send customers to **checkout**. Kelviq takes the payment and the tax.
36
+ 3. Your app **checks access** and **reports usage** with the SDK.
37
+ 4. Kelviq bills renewals and overage, and **pays you out**.
47
38
 
48
- No more subscription tables in your database. No sync jobs. No stale data. Kelviq is your source of truth.
49
-
50
-
51
-
52
-
53
- Stop scattering feature checks throughout your codebase. Check entitlements with one SDK call. Update plans from the dashboard.
54
-
55
-
56
-
57
-
58
- Change prices, plans, trials, or entitlements from the dashboard. Ship pricing changes instantly without waiting for engineering.
59
-
60
-
61
- ---
62
-
63
- ## Who kelviq is for
64
-
65
- - **AI product companies** — track what your autonomous agents do for each customer and bill based on actual usage. Maintain healthy unit economics as your underlying compute costs scale.
66
-
67
- - **Developers** — integrate billing without spending weeks writing complex custom usage code, database sync jobs, or webhook listeners.
68
-
69
- - **Product managers** — take ownership of pricing and plans. Run experiments, roll out promotions, and update entitlements directly from the dashboard without waiting for engineering.
70
-
71
- - **Founders** — Launch globally from day one without becoming a tax expert. Kelviq acts as your merchant of record and takes on the full legal liability for VAT, sales tax, and compliance so you can focus on building the product.
72
-
73
- - **Digital creators** — Sell your e-books, software, design assets, or courses with zero hassle. Kelviq provides a complete, all-in-one solution that securely delivers your files, generates license keys, and handles all global taxes for you—no code or complex setup required.
39
+ Create a product, a plan, and your first feature.
74
40
 
75
41
  ## Need help?
76
42
 
77
- Have questions, need help with implementation, or want a walkthrough?
78
- Email us at **hi@kelviq.com** or [book a demo](https://tidycal.com/neravath/15-minute-meeting).
79
-
80
- ---
43
+ Email us at **hi@kelviq.com** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
@@ -7,28 +7,28 @@ Kelviq operates as your Merchant of Record (MoR). This means we are the legal re
7
7
 
8
8
  ---
9
9
 
10
- ## What is a Merchant of Record (MOR)?
10
+ ## What is a Merchant of Record (MoR)?
11
11
 
12
12
  The "Merchant of Record" is the most important concept to understand when using Kelviq. It's the engine that enables you to sell globally without handling the legal and financial complexity yourself.
13
13
 
14
14
  A Merchant of Record is the entity that is **legally responsible for selling a product to an end customer**.
15
15
 
16
- When a customer buys your product, their financial transaction is with the MOR (Kelviq), not with your company. We take on the responsibility for that sale, handling all the complex financial and legal requirements that come with it.
16
+ When a customer buys your product, their financial transaction is with the MoR (Kelviq), not with your company. We take on the responsibility for that sale, handling all the complex financial and legal requirements that come with it.
17
17
 
18
- This model allows you to focus 100% on building your product while we handle the entire checkout, tax, and compliance backend.
18
+ You build your product. Kelviq handles checkout, tax, and compliance.
19
19
 
20
20
  ---
21
21
 
22
- ### The Core Responsibilities of an MOR
22
+ ### The Core Responsibilities of an MoR
23
23
 
24
- By acting as your MOR, Kelviq takes on a massive amount of financial and legal liability. This is the "hard part" of global sales that we handle for you:
24
+ As your MoR, Kelviq does three jobs for you:
25
25
 
26
- * **📈 Global Tax & Compliance**
27
- This is the single biggest challenge of selling online. An MOR is responsible for calculating, collecting, and remitting sales taxes like VAT (Europe), GST (Australia), JCT (Japan), and state-level sales tax in the U.S.
28
- * **🛡️ Financial Liability & Risk**
29
- The MOR is financially liable for every transaction. This includes bearing the cost of customer chargebacks (disputes) and all fraudulent payments.
30
- * **⚖️ Payment & Regulatory Burden**
31
- The MOR ensures that every part of the checkout and payment process is compliant with global regulations, such as PCI-DSS and PSD2/SCA.
26
+ * **Global tax and compliance**
27
+ Kelviq calculates, collects, and files sales taxes like VAT (EU and UK), GST (India, Australia, Singapore, New Zealand), GST/HST (Canada), JCT (Japan), and state-level sales tax in the U.S.
28
+ * **Fraud and disputes**
29
+ Kelviq screens payments for fraud and handles every dispute with the bank. Each dispute costs \$15, whatever the outcome. See [Fees](/getstarted/fees#disputes-and-chargebacks).
30
+ * **Payment regulations**
31
+ The MoR ensures that every part of the checkout and payment process is compliant with global regulations, such as PCI-DSS and PSD2/SCA.
32
32
 
33
33
  ### How it Works: A Real-World Example
34
34
 
@@ -37,12 +37,12 @@ To understand exactly where the money goes, let's look at a specific transaction
37
37
  1. **The Sale:** A customer in **Germany** visits your site and buys your product. You have set the price at **€50.00**.
38
38
  2. **The Calculation:** Kelviq automatically detects the customer is in Germany and adds the 19% German VAT (€9.50). The customer pays a total of **€59.50**.
39
39
  3. **The Legal Transaction:** The customer's €59.50 transaction is legally with Kelviq. We are the "seller" on their invoice.
40
- 4. **Tax Remittance (The Hard Part):** At the end of the quarter, our finance team takes that **€9.50** and files the VAT return with the German authorities. You never see or touch this tax money, so you never have to worry about it.
41
- 5. **Your Payout:** We take our simple platform fee from the original **€50.00** and deposit the rest directly into your bank account.
40
+ 4. **Tax remittance:** At the end of the quarter, our finance team takes that **€9.50** and files the VAT return with the German authorities. The tax never enters your balance, so there's nothing for you to file.
41
+ 5. **Your Payout:** We take our fee from the full **€59.50** the customer paid, send the €9.50 VAT to the German tax authority, and pay the rest out to your bank account. See [Fees](/getstarted/fees).
42
42
 
43
43
  You get your expected revenue. We handle the legal and tax complexity of the extra €9.50.
44
44
 
45
- ### MOR vs. Payment Service Provider (PSP)
45
+ ### MoR vs. Payment Service Provider (PSP)
46
46
 
47
47
  A PSP (like Stripe or PayPal) gives you the *tools* to process a payment, but **you** are still the seller of record.
48
48
 
@@ -50,15 +50,9 @@ A PSP (like Stripe or PayPal) gives you the *tools* to process a payment, but **
50
50
  | :--- | :--- | :--- |
51
51
  | **Who is the Seller?** | **You** are the seller of record. | **Kelviq** is the seller of record. |
52
52
  | **Tax Liability** | **Your responsibility.** You must register, file, and remit. | **Kelviq's responsibility.** We handle all filing and payments. |
53
- | **Fraud Risk** | **You.** You lose the sale + fees on chargebacks. | **Kelviq.** We take the financial hit. |
54
- | **Time to Market** | Weeks or months of setup. | Minutes. |
53
+ | **Fraud and disputes** | **You.** You screen for fraud and fight each dispute yourself. | **Kelviq.** We screen payments and handle disputes. \$15 per dispute. |
54
+ | **Time to Market** | Weeks or months of setup. | Same day. |
55
55
 
56
- ### Your Two Model Choices in Kelviq
56
+ ### Prefer to stay the merchant of record yourself?
57
57
 
58
- Kelviq is designed to be flexible, offering two primary ways to operate:
59
-
60
- **1. Kelviq as your Merchant of Record (Recommended)**
61
- This is the default and recommended model. When you sign up, Kelviq acts as your MOR, handling all the responsibilities described on this page. You get the full all-in-one platform with zero compliance overhead.
62
-
63
- **2. Bring Your Own Stripe Account (BYOA)**
64
- For businesses that prefer to remain the Merchant of Record, you can connect your own Stripe account. In this model, **you are responsible for your own tax, fraud, and compliance**, but you still get access to all of Kelviq's monetization features—such as our usage-based billing engine, feature flagging, and localization tools. Please contact us at hi@kelviq.com to enable this option.
58
+ Kelviq also offers BYOA (bring your own account). Email [hi@kelviq.com](mailto:hi@kelviq.com) to set it up.
@@ -0,0 +1,98 @@
1
+ ---
2
+ title: "Documentation"
3
+ slug: "getstarted/overview"
4
+ section: "getstarted"
5
+ description: "What Kelviq does, how it fits into your app, and where to start."
6
+ ---
7
+ <div className="kq-home kq-intro">
8
+
9
+ <section className="kq-hero2">
10
+ <div className="kq-hero2-text">
11
+ <p className="kq-crumb">Get started</p>
12
+ <h1 className="kq-hero2-title">Documentation</h1>
13
+ <p className="kq-hero2-sub">
14
+ Kelviq is a merchant of record with billing built in. You set your prices and plans, Kelviq sells them, collects the tax, and pays you out. Your app asks Kelviq what each customer can use.
15
+ </p>
16
+ <a className="kq-go" href="/quickstart/dashboard-setup">Get started <span className="kq-go-arrow">→</span></a>
17
+ <div className="kq-chips">
18
+ <a className="kq-chip" href="/getstarted/introduction-to-kelviq#what-kelviq-handles"><span className="kq-chip-ico" />Will Kelviq work for my product?</a>
19
+ <a className="kq-chip" href="/payouts/overview#do-i-need-a-stripe-account"><span className="kq-chip-ico" />Do I need a Stripe account?</a>
20
+ <a className="kq-chip" href="/getstarted/fees"><span className="kq-chip-ico" />What does Kelviq cost?</a>
21
+ <a className="kq-chip" href="/product-catalog/usage-based-billing"><span className="kq-chip-ico" />Can I charge per token or API call?</a>
22
+ <a className="kq-chip" href="/guides/set-up-with-ai"><span className="kq-chip-ico" />What's the fastest way to integrate Kelviq?</a>
23
+ </div>
24
+ </div>
25
+ <img className="kq-hero2-art" src="/images/illustrations/hero-side.svg" alt="" noZoom />
26
+ </section>
27
+
28
+ <section className="kq-section">
29
+ <h2 className="kq-section-title">Start here</h2>
30
+ <div className="kq-grid">
31
+ <a className="kq-card" href="/getstarted/introduction-to-kelviq">
32
+ <img className="kq-art" src="/images/illustrations/how-kelviq-works.svg" alt="" noZoom />
33
+ <h3>How Kelviq works</h3>
34
+ <p>Products, plans, features and customers, and what Kelviq handles for you.</p>
35
+ </a>
36
+ <a className="kq-card" href="/quickstart/dashboard-setup">
37
+ <img className="kq-art" src="/images/illustrations/dashboard-setup.svg" alt="" noZoom />
38
+ <h3>Set up your dashboard</h3>
39
+ <p>Create a product, a plan, and your first feature.</p>
40
+ </a>
41
+ <a className="kq-card" href="/quickstart/integrate-with-your-app">
42
+ <img className="kq-art" src="/images/illustrations/integrate.svg" alt="" noZoom />
43
+ <h3>Integrate with your app</h3>
44
+ <p>Send customers to checkout, check access, and report usage.</p>
45
+ </a>
46
+ <a className="kq-card" href="/ai/overview">
47
+ <img className="kq-art" src="/images/illustrations/build-with-ai.svg" alt="" noZoom />
48
+ <h3>Build with AI</h3>
49
+ <p>Let Claude Code, Cursor or Codex set up Kelviq, or connect agents to the MCP server.</p>
50
+ </a>
51
+ </div>
52
+ </section>
53
+
54
+ <section className="kq-section">
55
+ <h2 className="kq-section-title">Sell</h2>
56
+ <div className="kq-grid">
57
+ <a className="kq-card" href="/product-catalog/subscriptions">
58
+ <img className="kq-art" src="/images/illustrations/pricing-models.svg" alt="" noZoom />
59
+ <h3>Pricing models</h3>
60
+ <p>Subscriptions, one-time, per seat, usage-based, pay as you go, trials.</p>
61
+ </a>
62
+ <a className="kq-card" href="/checkout/checkout-examples">
63
+ <img className="kq-art" src="/images/illustrations/checkout.svg" alt="" noZoom />
64
+ <h3>Checkout</h3>
65
+ <p>One-page hosted checkout with local payment methods, in light and dark.</p>
66
+ </a>
67
+ <a className="kq-card" href="/customer-portal/overview">
68
+ <img className="kq-art" src="/images/illustrations/customer-portal.svg" alt="" noZoom />
69
+ <h3>Customer portal</h3>
70
+ <p>Customers manage plans, payment methods and invoices themselves.</p>
71
+ </a>
72
+ <a className="kq-card" href="/payouts/overview">
73
+ <img className="kq-art" src="/images/illustrations/payouts.svg" alt="" noZoom />
74
+ <h3>Payouts</h3>
75
+ <p>When and how you get paid, and what the fees are.</p>
76
+ </a>
77
+ </div>
78
+ </section>
79
+
80
+ <section className="kq-section">
81
+ <h2 className="kq-section-title">Reference</h2>
82
+ <div className="kq-grid kq-grid-3">
83
+ <a className="kq-card kq-card-row" href="/api-reference/introduction">
84
+ <div className="kq-tile kq-tile-sm"><span className="kq-ico" style={{ WebkitMaskImage: "url(/icons/brackets-curly.svg)", maskImage: "url(/icons/brackets-curly.svg)" }} /></div>
85
+ <div><h3>API reference</h3><p>Every endpoint, with examples.</p></div>
86
+ </a>
87
+ <a className="kq-card kq-card-row" href="/backend-integration/node-sdk">
88
+ <div className="kq-tile kq-tile-sm"><span className="kq-ico" style={{ WebkitMaskImage: "url(/icons/cube.svg)", maskImage: "url(/icons/cube.svg)" }} /></div>
89
+ <div><h3>SDKs</h3><p>Node, Python, React and JavaScript.</p></div>
90
+ </a>
91
+ <a className="kq-card kq-card-row" href="/changelog">
92
+ <div className="kq-tile kq-tile-sm"><span className="kq-ico" style={{ WebkitMaskImage: "url(/icons/clock-rotate.svg)", maskImage: "url(/icons/clock-rotate.svg)" }} /></div>
93
+ <div><h3>Changelog</h3><p>What shipped, every Friday.</p></div>
94
+ </a>
95
+ </div>
96
+ </section>
97
+
98
+ </div>