@kelviq/mcp-server 1.2.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +40 -3
- package/dist/config.d.ts +5 -0
- package/dist/config.js +1 -0
- package/dist/config.js.map +1 -1
- package/dist/docs/ai/docs-for-agents.md +21 -0
- package/dist/docs/ai/overview.md +43 -0
- package/dist/docs/api-reference/authentication.md +9 -3
- package/dist/docs/api-reference/introduction.md +23 -2
- package/dist/docs/backend-integration/node-sdk.md +12 -6
- package/dist/docs/backend-integration/python-sdk.md +14 -8
- package/dist/docs/changelog.md +369 -3
- package/dist/docs/checkout/checkout-configuration.md +25 -75
- package/dist/docs/checkout/checkout-design.md +76 -0
- package/dist/docs/checkout/checkout-examples.md +212 -0
- package/dist/docs/checkout/checkout-metadata.md +1 -1
- package/dist/docs/checkout/custom-fields.md +60 -0
- package/dist/docs/checkout/embed-checkout.md +280 -0
- package/dist/docs/checkout/payment-methods/upi.md +69 -0
- package/dist/docs/checkout/payment-methods.md +119 -0
- package/dist/docs/checkout/static-checkout-url.md +3 -2
- package/dist/docs/cli/commands.md +57 -4
- package/dist/docs/cli/kelviq-config.md +1 -1
- package/dist/docs/cli/overview.md +1 -0
- package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
- package/dist/docs/customer-portal/overview.md +7 -7
- package/dist/docs/customer-portal/retention.md +109 -0
- package/dist/docs/customers-management/overview.md +105 -0
- package/dist/docs/frontend-integration/js-sdk.md +11 -11
- package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
- package/dist/docs/frontend-integration/react-sdk.md +8 -49
- package/dist/docs/frontend-integration/react-ui.md +8 -6
- package/dist/docs/getstarted/fees.md +27 -11
- package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
- package/dist/docs/getstarted/merchant-of-record.md +18 -24
- package/dist/docs/getstarted/overview.md +98 -0
- package/dist/docs/getstarted/review-process.md +59 -59
- package/dist/docs/guides/agent-toolkit.md +14 -9
- package/dist/docs/guides/mcp-server.md +24 -9
- package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
- package/dist/docs/guides/sandbox.md +6 -4
- package/dist/docs/guides/set-up-with-ai.md +43 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
- package/dist/docs/guides/subscription-integration.md +1 -1
- package/dist/docs/guides/test-payments.md +640 -0
- package/dist/docs/guides/webhooks.md +182 -30
- package/dist/docs/integrations/woocommerce.md +88 -0
- package/dist/docs/integrations/zapier.md +22 -0
- package/dist/docs/legal/account-and-funds.md +59 -0
- package/dist/docs/legal/approved-prohibited-policy.md +32 -27
- package/dist/docs/legal/payment-flow-diagram.md +7 -7
- package/dist/docs/manifest.json +160 -41
- package/dist/docs/openapi.json +1359 -109
- package/dist/docs/payouts/overview.md +14 -12
- package/dist/docs/payouts/payout-account.md +1 -1
- package/dist/docs/payouts/transactions.md +3 -3
- package/dist/docs/product-catalog/create-a-feature.md +3 -3
- package/dist/docs/product-catalog/digital-downloads.md +5 -5
- package/dist/docs/product-catalog/discounts.md +2 -2
- package/dist/docs/product-catalog/entitlements.md +20 -27
- package/dist/docs/product-catalog/free-and-trials.md +5 -5
- package/dist/docs/product-catalog/license-keys.md +56 -29
- package/dist/docs/product-catalog/links.md +3 -3
- package/dist/docs/product-catalog/location-based-pricing.md +6 -10
- package/dist/docs/product-catalog/one-time-payments.md +3 -7
- package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
- package/dist/docs/product-catalog/plans.md +22 -19
- package/dist/docs/product-catalog/products.md +11 -3
- package/dist/docs/product-catalog/proration.md +69 -0
- package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
- package/dist/docs/product-catalog/subscriptions.md +52 -22
- package/dist/docs/product-catalog/tax-settings.md +8 -8
- package/dist/docs/product-catalog/usage-alerts.md +7 -7
- package/dist/docs/product-catalog/usage-based-billing.md +156 -29
- package/dist/docs/product-catalog/usage-limits.md +78 -0
- package/dist/docs/promotions/create-a-promotion.md +2 -2
- package/dist/docs/promotions/overview.md +1 -1
- package/dist/docs/quickstart/core-concepts.md +36 -30
- package/dist/docs/quickstart/dashboard-setup.md +26 -22
- package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
- package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
- package/dist/docs/sales/checkout-sessions.md +28 -39
- package/dist/docs/sales/orders.md +30 -54
- package/dist/docs/settings/customer-emails.md +52 -0
- package/dist/docs/settings/members.md +27 -0
- package/dist/docs/settings/profile.md +26 -0
- package/dist/docs/settings/zapier.md +22 -0
- package/dist/http/errors.d.ts +20 -1
- package/dist/http/errors.js +83 -31
- package/dist/http/errors.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +54 -0
- package/dist/schemas/kelviq.js +64 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +3 -2
- package/dist/server.js.map +1 -1
- package/dist/tools/_resolve.js +14 -10
- package/dist/tools/_resolve.js.map +1 -1
- package/dist/tools/features.js +9 -2
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/imports.d.ts +68 -0
- package/dist/tools/imports.js +242 -0
- package/dist/tools/imports.js.map +1 -0
- package/dist/tools/index.d.ts +2 -1
- package/dist/tools/index.js +4 -1
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/product-files.js +10 -3
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +10 -3
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +14 -4
- package/dist/tools/products.js.map +1 -1
- 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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 **
|
|
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
|
|
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
|
|
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
|
|
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**:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
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
|
|
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
|
-
|
|
18
|
+
You build your product. Kelviq handles checkout, tax, and compliance.
|
|
19
19
|
|
|
20
20
|
---
|
|
21
21
|
|
|
22
|
-
### The Core Responsibilities of an
|
|
22
|
+
### The Core Responsibilities of an MoR
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
As your MoR, Kelviq does three jobs for you:
|
|
25
25
|
|
|
26
|
-
*
|
|
27
|
-
|
|
28
|
-
*
|
|
29
|
-
|
|
30
|
-
*
|
|
31
|
-
The
|
|
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
|
|
41
|
-
5. **Your Payout:** We take our
|
|
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
|
-
###
|
|
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
|
|
54
|
-
| **Time to Market** | Weeks or months of setup. |
|
|
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
|
-
###
|
|
56
|
+
### Prefer to stay the merchant of record yourself?
|
|
57
57
|
|
|
58
|
-
Kelviq
|
|
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>
|