@kelviq/mcp-server 0.4.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -26
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +114 -34
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +102 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/server.js +10 -1
- package/dist/server.js.map +1 -1
- package/package.json +1 -1
|
@@ -53,29 +53,36 @@ Server API Keys have full API access. Never expose them in client-side code, com
|
|
|
53
53
|
|
|
54
54
|
## Environment variables
|
|
55
55
|
|
|
56
|
-
Environment variables **override** the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys
|
|
56
|
+
Environment variables **override** the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys. `KELVIQ_SERVER_API_KEY` and `KELVIQ_ENV` work the same way as in the [MCP server](/guides/mcp-server); the environment-named keys are CLI-only.
|
|
57
57
|
|
|
58
58
|
| Variable | Purpose |
|
|
59
59
|
|---|---|
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `KELVIQ_EDGE_URL` | Override the edge
|
|
60
|
+
| `KELVIQ_SERVER_API_KEY` | Server key for the environment named by `KELVIQ_ENV`. |
|
|
61
|
+
| `KELVIQ_ENV` | `sandbox` (the default when unset, as in the MCP server) or `production`. |
|
|
62
|
+
| `KELVIQ_SANDBOX_SERVER_API_KEY` | Server key that always applies to sandbox. |
|
|
63
|
+
| `KELVIQ_PRODUCTION_SERVER_API_KEY` | Server key that always applies to production. |
|
|
64
|
+
| `KELVIQ_BASE_URL`, `KELVIQ_EDGE_URL` | Override the API or edge URL for the `KELVIQ_ENV` environment. You almost never need these. |
|
|
65
|
+
|
|
66
|
+
- A variable named for an environment wins over `KELVIQ_SERVER_API_KEY`. Use `KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` when one shell needs both keys, for example for `kelviq promote`.
|
|
67
|
+
- `KELVIQ_ENV` only decides which environment `KELVIQ_SERVER_API_KEY` belongs to. It never makes a command target production — only `--prod` does.
|
|
68
|
+
- Any value other than `sandbox` or `production` makes commands fail rather than guess.
|
|
65
69
|
|
|
66
70
|
A typical CI setup skips `kelviq login` entirely:
|
|
67
71
|
|
|
68
72
|
```yaml
|
|
69
73
|
# e.g. GitHub Actions
|
|
70
74
|
env:
|
|
71
|
-
|
|
75
|
+
KELVIQ_SERVER_API_KEY: ${{ secrets.KELVIQ_SANDBOX_SERVER_API_KEY }}
|
|
76
|
+
KELVIQ_ENV: sandbox
|
|
72
77
|
```
|
|
73
78
|
|
|
74
79
|
```shell
|
|
75
|
-
kelviq pull --force # authenticates from the environment
|
|
80
|
+
kelviq pull --force # authenticates from the environment variables
|
|
76
81
|
```
|
|
77
82
|
|
|
78
|
-
|
|
83
|
+
For `kelviq promote` in CI, set both `KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` instead.
|
|
84
|
+
|
|
85
|
+
If a command needs a key and finds none — neither in the environment nor stored — it fails with a message naming the variables to set and where to get a key. If `KELVIQ_SERVER_API_KEY` is set for the other environment, the message says so.
|
|
79
86
|
|
|
80
87
|
---
|
|
81
88
|
|
|
@@ -85,6 +92,7 @@ If a command needs a key and finds none — neither in the environment nor store
|
|
|
85
92
|
|
|
86
93
|
```text
|
|
87
94
|
Environment : sandbox (default — use --prod to target production)
|
|
95
|
+
KELVIQ_ENV : unset (sandbox) — unprefixed KELVIQ_* vars apply to sandbox
|
|
88
96
|
Sandbox URL : https://sandboxapi.kelviq.com/api/v1
|
|
89
97
|
Prod URL : https://api.kelviq.com/api/v1
|
|
90
98
|
Sandbox key : set
|
|
@@ -98,6 +98,7 @@ The plan lifecycle (draft → published) is also deliberately absent: the config
|
|
|
98
98
|
| `product` | slug | yes | Identifier of the parent product. |
|
|
99
99
|
| `description` | string | no | Free-text description. |
|
|
100
100
|
| `isVisible` | boolean | no | Whether the plan is publicly visible. |
|
|
101
|
+
| `license` | object | no | License-key issuance settings for orders on this plan — see below. |
|
|
101
102
|
| `entitlements` | array | no | What the plan grants — see below. |
|
|
102
103
|
| `prices` | array | no | The plan's price set — see below. |
|
|
103
104
|
| `metadata` | object | no | Arbitrary key-value metadata. |
|
|
@@ -119,6 +120,39 @@ Entitlements accept additional keys beyond these — the shape varies by feature
|
|
|
119
120
|
|
|
120
121
|
Some enum values (for example `EVERY_28_DAYS`) are only available when enabled for your account. The CLI's enum fields autocomplete the standard values but accept any string: values it doesn't recognize are passed through verbatim, and the API validates them when you push. This means new server-side values work without a CLI update.
|
|
121
122
|
|
|
123
|
+
### License keys
|
|
124
|
+
|
|
125
|
+
When [license keys](/product-catalog/license-keys) are enabled on a plan, every order generates a key. The `license` object holds the plan-level issuance settings — the same controls as the dashboard's **License keys** section:
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
export const team = plan({
|
|
129
|
+
identifier: 'team',
|
|
130
|
+
name: 'Team',
|
|
131
|
+
product: 'my-app',
|
|
132
|
+
license: {
|
|
133
|
+
enabled: true,
|
|
134
|
+
activationLimitEnabled: true,
|
|
135
|
+
activationLimit: 5, // up to 5 devices per key
|
|
136
|
+
hasExpiry: true,
|
|
137
|
+
durationValue: 12,
|
|
138
|
+
durationUnit: 'MONTH', // keys expire 12 months after purchase
|
|
139
|
+
},
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
| Field | Type | Required | Description |
|
|
144
|
+
|---|---|---|---|
|
|
145
|
+
| `enabled` | boolean | no | Whether orders for this plan issue license keys. |
|
|
146
|
+
| `activationLimitEnabled` | boolean | no | Cap how many devices one key can be activated on. When `false`, activations are unlimited. |
|
|
147
|
+
| `activationLimit` | integer ≥ 1 | no | The cap, when `activationLimitEnabled` is `true`. |
|
|
148
|
+
| `hasExpiry` | boolean | no | Whether keys expire. When `false`, keys never expire. |
|
|
149
|
+
| `durationValue` | integer ≥ 1 | no | How long a key stays valid after purchase, in `durationUnit`s. |
|
|
150
|
+
| `durationUnit` | enum | no | `DAY`, `MONTH`, or `YEAR`. |
|
|
151
|
+
|
|
152
|
+
The object is compared and sent as one unit: `kelviq push` shows the old and new license config side by side and sends the whole object when anything in it differs. A plan that **omits** `license` leaves the remote license settings untouched, so a config file that doesn't mention license keys never disables them. Additional keys are passed through to the API.
|
|
153
|
+
|
|
154
|
+
Individual issued keys — activating, validating, or deactivating a customer's key — are per-customer runtime operations, not catalog state. They live in the API, the SDKs, and the [MCP server](/guides/mcp-server), not in this file.
|
|
155
|
+
|
|
122
156
|
### Prices
|
|
123
157
|
|
|
124
158
|
The price envelope is validated; the charge structures inside it are deliberately loose and passed through to the API as-is:
|
|
@@ -138,4 +172,4 @@ A pulled config reproduces your remote prices in full, including nested charge s
|
|
|
138
172
|
|
|
139
173
|
## Schemas as values
|
|
140
174
|
|
|
141
|
-
Everything the builders validate against is exported from `@kelviq/cli/config` if you want to reuse it — `productDefSchema`, `featureDefSchema`, `planDefSchema`, `entitlementDefSchema`, `priceDefSchema`, `kelviqConfigSchema`, the enums (`taxCodeSchema`, `featureTypeSchema`, `priceTypeSchema`, `resetSchema`, `taxBehaviorSchema`, `identifierSchema`), and their TypeScript types (`ProductDef`, `FeatureDef`, `PlanDef`, and so on). They're standard [Zod](https://zod.dev) schemas.
|
|
175
|
+
Everything the builders validate against is exported from `@kelviq/cli/config` if you want to reuse it — `productDefSchema`, `featureDefSchema`, `planDefSchema`, `entitlementDefSchema`, `priceDefSchema`, `licenseDefSchema`, `kelviqConfigSchema`, the enums (`taxCodeSchema`, `featureTypeSchema`, `priceTypeSchema`, `resetSchema`, `taxBehaviorSchema`, `durationUnitSchema`, `identifierSchema`), and their TypeScript types (`ProductDef`, `FeatureDef`, `PlanDef`, `LicenseDef`, and so on). They're standard [Zod](https://zod.dev) schemas.
|
|
@@ -6,6 +6,8 @@ description: "Pricing-as-code for Kelviq — define your products, features, and
|
|
|
6
6
|
---
|
|
7
7
|
**The Kelviq CLI is in beta.** It's fully functional — and safe by design, with previews and confirmations before every write — but commands, flags, and the `--json` output shape may still change between releases. Pin an exact version in CI and review the release notes before upgrading.
|
|
8
8
|
|
|
9
|
+
Working with an AI coding agent? The [Agent Toolkit](/guides/agent-toolkit)'s `pricing-as-code` skill teaches agents this exact workflow — including the rule that agents preview diffs freely but never apply changes without your approval.
|
|
10
|
+
|
|
9
11
|
The Kelviq CLI (`@kelviq/cli`) lets you manage your pricing catalog as **code** instead of dashboard clicks. Your products, features, plans, entitlements, and prices live in a single typed TypeScript file — `kelviq.config.ts` — that you can review, diff, and version-control like the rest of your codebase.
|
|
10
12
|
|
|
11
13
|
```ts
|
|
@@ -43,6 +43,10 @@ You can create records manually.
|
|
|
43
43
|
|
|
44
44
|
<img height="200" src="/images/create-customer-modal.png" />
|
|
45
45
|
|
|
46
|
+
More than one customer record can use the same email address, but every record must have a unique **Identifier**. The API calls this value `customerId`.
|
|
47
|
+
|
|
48
|
+
When recreating a test customer, you can reuse the email address, but you must provide a new Identifier. An Identifier cannot be reused after its customer is archived. If you receive a `customer already exists` error, check the Identifier first.
|
|
49
|
+
|
|
46
50
|
## Manage existing customers
|
|
47
51
|
|
|
48
52
|
You can edit details or revoke access from the list view.
|
|
@@ -61,6 +65,8 @@ Archiving makes a customer inactive and revokes their access. Click the **three
|
|
|
61
65
|
|
|
62
66
|
You will see a confirmation warning. Click **Confirm** to proceed.
|
|
63
67
|
|
|
68
|
+
Kelviq archives customers; it does not hard-delete them. The archived record keeps its Identifier, so that value cannot be reused. To create another customer with the same email address, use a new Identifier.
|
|
69
|
+
|
|
64
70
|
You cannot archive a customer with an active subscription. You must cancel their subscription first.
|
|
65
71
|
|
|
66
72
|
## Customer details
|
|
@@ -73,21 +79,19 @@ This page holds the source of truth for that user. You can see their unique Bill
|
|
|
73
79
|
|
|
74
80
|
### Subscriptions
|
|
75
81
|
|
|
76
|
-
This section lists active and past plans. It shows the status, such as Active or Canceled, and the relevant dates.
|
|
82
|
+
This section lists active and past plans. It shows the status, such as Active or Canceled, and the relevant dates. For a cancelled subscription, the date it was cancelled appears alongside the status.
|
|
83
|
+
|
|
84
|
+
### Files, links, and license keys
|
|
77
85
|
|
|
78
|
-
|
|
79
|
-
You can manually subscribe a customer to a plan from here.
|
|
86
|
+
The customer detail page shows the deliverables the customer received through their plans:
|
|
80
87
|
|
|
81
|
-
|
|
88
|
+
* **Files** — View and download digital files available to the customer.
|
|
89
|
+
* **Links** — Open private or external resource links attached to the plan.
|
|
90
|
+
* **License keys** — View issued license keys and use the available license-management controls.
|
|
82
91
|
|
|
83
|
-
|
|
84
|
-
2. Set the **Billing period** and **Currency**.
|
|
85
|
-
3. Select the **Features** included in this specific sub.
|
|
86
|
-
4. Set the **Usage limits** or allowances.
|
|
87
|
-
5. Choose a **Start date**. You can also adjust the **Free trial** period here.
|
|
92
|
+
These sections let support teams confirm access without opening each order separately.
|
|
88
93
|
|
|
89
|
-
|
|
90
|
-
You can also modify an existing subscription. Click on the subscription card to update terms, change status, or extend trial dates.
|
|
94
|
+
For catalog setup, see [Digital Downloads](/product-catalog/digital-downloads), [Links](/product-catalog/links), and [License Key Management](/product-catalog/license-keys).
|
|
91
95
|
|
|
92
96
|
### Entitlements
|
|
93
97
|
|
|
@@ -101,11 +105,3 @@ You often need to make exceptions for specific users. You can do that here witho
|
|
|
101
105
|
Changes made here apply only to this specific customer.
|
|
102
106
|
|
|
103
107
|
<img height="200" src="/images/entitlements-details.png" />
|
|
104
|
-
|
|
105
|
-
### Usage
|
|
106
|
-
|
|
107
|
-
This tracks consumption for usage-based billing.
|
|
108
|
-
* Graphs show usage trends over time.
|
|
109
|
-
* Hover over the data to see exact numbers for specific periods.
|
|
110
|
-
|
|
111
|
-
<img height="200" src="/images/entitlements-full-details.png" />
|
|
@@ -1,72 +1,54 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "Managing
|
|
2
|
+
title: "Managing payment methods"
|
|
3
3
|
slug: "customer-portal/managing-payment-methods"
|
|
4
4
|
section: "customer-portal"
|
|
5
|
-
description: "
|
|
5
|
+
description: "How your customers add, update, and remove payment methods"
|
|
6
6
|
---
|
|
7
|
-
##
|
|
7
|
+
## Multiple customer records with one email
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
More than one customer record can use the same email address. Each record has a unique customer ID and keeps its own subscriptions, payment methods, and billing details.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
If a customer sees more than one record in the portal, they should select the record connected to the subscription they want to manage.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## How Kelviq chooses a payment method
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
When a subscription renews, Kelviq first charges the payment method selected when the subscription was created.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
* Payment methods
|
|
19
|
-
* Billing details
|
|
17
|
+
If that payment method fails because it has expired, has insufficient funds, or cannot be processed, Kelviq uses the saved default payment method as a fallback.
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
## How customers pay a failed card invoice
|
|
22
20
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
## Payment Methods and Fallback
|
|
26
|
-
|
|
27
|
-
When managing your subscriptions and billing details, it's important to understand how payment methods are prioritized to ensure your services remain uninterrupted.
|
|
21
|
+
If an automatic card payment fails, your customer gets an email with a link to pay the invoice. They can also open **Settings > Billing** in the Customer Portal to add or update a payment method.
|
|
28
22
|
|
|
29
|
-
|
|
23
|
+
Paying an invoice manually does not turn off automatic payments. The customer's payment authorization remains active for future renewals.
|
|
30
24
|
|
|
31
|
-
|
|
25
|
+
See [Failed subscription payments](/product-catalog/subscriptions#failed-subscription-payments) for the card retry schedule.
|
|
32
26
|
|
|
33
|
-
|
|
27
|
+
## How customers manage payment methods
|
|
34
28
|
|
|
35
|
-
|
|
29
|
+
### Add a payment method
|
|
36
30
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
---
|
|
31
|
+
1. The customer opens **Settings** from the main menu and selects **Billing**.
|
|
32
|
+
2. They select the customer record they want to update.
|
|
33
|
+
3. They click **Add Payment Method**.
|
|
34
|
+
4. They enter the payment details and click **Save**.
|
|
42
35
|
|
|
43
|
-
|
|
36
|
+
The new payment method appears under **Saved payment methods**.
|
|
44
37
|
|
|
45
|
-
|
|
38
|
+
### Set the default payment method
|
|
46
39
|
|
|
47
|
-
|
|
40
|
+
The default payment method is used as a fallback if the payment method attached to a subscription fails.
|
|
48
41
|
|
|
49
|
-
|
|
42
|
+
1. The customer opens **Settings > Billing**.
|
|
43
|
+
2. They find the payment method they want to use as the default.
|
|
44
|
+
3. They click the star icon next to it.
|
|
50
45
|
|
|
51
|
-
|
|
52
|
-
2. Locate the specific customer account you wish to update (if you have multiple accounts).
|
|
53
|
-
3. Click on the **Add Payment Method** button.
|
|
54
|
-
4. Securely enter your new credit card details (card number, expiration date, and CVC or other payment methods) and click save. The card will now appear under your "Saved payment methods".
|
|
55
|
-
|
|
56
|
-
### Setting a Default Payment Method
|
|
57
|
-
|
|
58
|
-
Your default payment method acts as a reliable fallback if an active subscription charge fails.
|
|
59
|
-
|
|
60
|
-
1. Navigate to **Settings** > **Billing**.
|
|
61
|
-
2. Find the card you want to prioritize under your saved payment methods.
|
|
62
|
-
3. Click the **star icon** next to the saved card to set the it as default. You should see a "DEFAULT" badge appear next to the card, indicating it is now your primary fallback payment method
|
|
63
|
-
|
|
64
|
-
---
|
|
46
|
+
The portal adds a **Default** badge to the selected payment method.
|
|
65
47
|
|
|
66
|
-
###
|
|
48
|
+
### Delete a payment method
|
|
67
49
|
|
|
68
|
-
|
|
50
|
+
Customers cannot delete their current default payment method. They must set another payment method as the default first.
|
|
69
51
|
|
|
70
|
-
1.
|
|
71
|
-
2.
|
|
72
|
-
3.
|
|
52
|
+
1. The customer opens **Settings > Billing**.
|
|
53
|
+
2. They find the payment method they want to remove.
|
|
54
|
+
3. They click the trash icon next to it.
|
|
@@ -36,7 +36,7 @@ function App() {
|
|
|
36
36
|
return (
|
|
37
37
|
<KelviqProvider
|
|
38
38
|
accessToken="YOUR_ACCESS_TOKEN"
|
|
39
|
-
|
|
39
|
+
productId="YOUR_PRODUCT_ID"
|
|
40
40
|
customerId="OPTIONAL_CUSTOMER_ID"
|
|
41
41
|
>
|
|
42
42
|
|
|
@@ -60,7 +60,7 @@ function App() {
|
|
|
60
60
|
return (
|
|
61
61
|
<KelviqProvider
|
|
62
62
|
accessToken="YOUR_ACCESS_TOKEN"
|
|
63
|
-
|
|
63
|
+
productId="YOUR_PRODUCT_ID"
|
|
64
64
|
customerId="OPTIONAL_CUSTOMER_ID"
|
|
65
65
|
>
|
|
66
66
|
|
|
@@ -81,8 +81,8 @@ The top-level provider component that initializes the SDK and manages the global
|
|
|
81
81
|
|
|
82
82
|
| Prop | Type | Description |
|
|
83
83
|
|------|------|-------------|
|
|
84
|
-
| `accessToken` | `string` | Your kelviq
|
|
85
|
-
| `
|
|
84
|
+
| `accessToken` | `string` | Your kelviq access token |
|
|
85
|
+
| `productId` | `string` | The unique identifier of the product to display the offering for |
|
|
86
86
|
|
|
87
87
|
#### Optional Props
|
|
88
88
|
|
|
@@ -115,7 +115,8 @@ The main pricing table component that displays all plans and handles user intera
|
|
|
115
115
|
|
|
116
116
|
| Prop | Type | Default | Description |
|
|
117
117
|
|------|------|---------|-------------|
|
|
118
|
-
| `customStyles` | `PricingTableStyle` | `{}` |
|
|
118
|
+
| `customStyles` | `PricingTableStyle` | `{}` | Style overrides (colors, typography, layout). Any field you omit falls back to the SDK defaults. |
|
|
119
|
+
| `pricingOptions` | `Partial<PricingOptions>` | `DEFAULT_PRICING_OPTIONS` | Price-formatting options (decimals, currency symbol/code, localization). Partial objects are merged with the defaults. |
|
|
119
120
|
| `customActionButton` | `CustomActionButton` | `undefined` | Custom button component |
|
|
120
121
|
| `customCheckIcon` | `React.ReactNode` | `undefined` | Custom check icon |
|
|
121
122
|
| `customUnCheckIcon` | `React.ReactNode` | `undefined` | Custom uncheck icon |
|
|
@@ -181,7 +182,7 @@ Renders a list of pricing plans with billing period switching.
|
|
|
181
182
|
| Prop | Type | Required | Description |
|
|
182
183
|
|------|------|----------|-------------|
|
|
183
184
|
| `plans` | `OfferingPlan[]` | Yes | Array of plans to display |
|
|
184
|
-
| `
|
|
185
|
+
| `pricingOptions` | `PricingOptions` | Yes | Price-formatting options |
|
|
185
186
|
| `billingPeriods` | `BillingPeriod[]` | Yes | Available billing periods |
|
|
186
187
|
| `countryCode` | `string` | Yes | Country code for localization |
|
|
187
188
|
| `currencyCode` | `string` | Yes | Currency code (e.g., "USD") |
|
|
@@ -203,7 +204,7 @@ Displays a single pricing plan card.
|
|
|
203
204
|
| Prop | Type | Required | Description |
|
|
204
205
|
|------|------|----------|-------------|
|
|
205
206
|
| `plan` | `OfferingPlan` | Yes | Plan data to display |
|
|
206
|
-
| `
|
|
207
|
+
| `pricingOptions` | `PricingOptions` | Yes | Price-formatting options |
|
|
207
208
|
| `period` | `ChargePeriodEnum` | Yes | Current billing period |
|
|
208
209
|
| `countryCode` | `string` | Yes | Country code |
|
|
209
210
|
| `currencyCode` | `string` | Yes | Currency code |
|
|
@@ -253,9 +254,10 @@ Renders the features list for a plan.
|
|
|
253
254
|
| `customCheckIcon` | `React.ReactNode` | No | Custom check icon |
|
|
254
255
|
| `customUnCheckIcon` | `React.ReactNode` | No | Custom uncheck icon |
|
|
255
256
|
| `customTooltipIcon` | `React.ReactNode` | No | Custom tooltip icon |
|
|
256
|
-
| `descriptionTooltipEnabled` | `boolean` | No | Enable tooltips |
|
|
257
257
|
| `onUsageChange` | `(featureId: string, quantity: number) => void` | No | Usage change handler |
|
|
258
258
|
|
|
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.
|
|
260
|
+
|
|
259
261
|
---
|
|
260
262
|
|
|
261
263
|
## 5. Data Types
|
|
@@ -316,6 +318,16 @@ interface PricingTableStyle {
|
|
|
316
318
|
typography: PricingTableTypographyConfig;
|
|
317
319
|
layout: PricingTableLayoutConfig;
|
|
318
320
|
}
|
|
321
|
+
|
|
322
|
+
// Price-formatting options (passed via the `pricingOptions` prop)
|
|
323
|
+
interface PricingOptions {
|
|
324
|
+
localization: boolean; // use the offering's locale/currency formatting
|
|
325
|
+
showDecimal: boolean; // show decimal places
|
|
326
|
+
minimumDecimalDigits: number; // minimum decimal places
|
|
327
|
+
maximumDecimalDigits: number; // maximum decimal places
|
|
328
|
+
showCurrencySymbol: boolean; // show the currency symbol (e.g. $)
|
|
329
|
+
showCurrencyCode: boolean; // show the currency code (e.g. USD)
|
|
330
|
+
}
|
|
319
331
|
```
|
|
320
332
|
|
|
321
333
|
### Color Configuration
|
|
@@ -371,6 +383,7 @@ interface PricingTableLayoutConfig {
|
|
|
371
383
|
maxWidth: number;
|
|
372
384
|
gap: number;
|
|
373
385
|
align: 'start' | 'center' | 'end';
|
|
386
|
+
tierSelectionType: 'switch' | 'tabs';
|
|
374
387
|
}
|
|
375
388
|
```
|
|
376
389
|
|
|
@@ -472,7 +485,28 @@ const customStyles: PricingTableStyle = {
|
|
|
472
485
|
};
|
|
473
486
|
```
|
|
474
487
|
|
|
475
|
-
### 6.3.
|
|
488
|
+
### 6.3. Price Formatting
|
|
489
|
+
|
|
490
|
+
How prices are formatted is configured entirely in the SDK via the `pricingOptions` prop. Pass only the fields you want to change — the rest fall back to `DEFAULT_PRICING_OPTIONS`:
|
|
491
|
+
|
|
492
|
+
```tsx
|
|
493
|
+
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
Defaults (`DEFAULT_PRICING_OPTIONS`):
|
|
497
|
+
|
|
498
|
+
```tsx
|
|
499
|
+
{
|
|
500
|
+
localization: true,
|
|
501
|
+
showDecimal: true,
|
|
502
|
+
minimumDecimalDigits: 0,
|
|
503
|
+
maximumDecimalDigits: 2,
|
|
504
|
+
showCurrencySymbol: true,
|
|
505
|
+
showCurrencyCode: false,
|
|
506
|
+
}
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
### 6.4. Custom Action Button
|
|
476
510
|
|
|
477
511
|
```tsx
|
|
478
512
|
const CustomButton: CustomActionButton = ({ onClick, children, plan, disabled }) => (
|
|
@@ -495,7 +529,7 @@ const CustomButton: CustomActionButton = ({ onClick, children, plan, disabled })
|
|
|
495
529
|
|
|
496
530
|
```
|
|
497
531
|
|
|
498
|
-
### 6.
|
|
532
|
+
### 6.5. noStyles Mode
|
|
499
533
|
|
|
500
534
|
For complete styling control, use the `noStyles` prop:
|
|
501
535
|
|
|
@@ -503,7 +537,7 @@ For complete styling control, use the `noStyles` prop:
|
|
|
503
537
|
|
|
504
538
|
```
|
|
505
539
|
|
|
506
|
-
### 6.
|
|
540
|
+
### 6.6. CSS Class Reference
|
|
507
541
|
|
|
508
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.
|
|
509
543
|
|
|
@@ -598,7 +632,7 @@ The SDK automatically handles subscription updates:
|
|
|
598
632
|
```tsx
|
|
599
633
|
<KelviqProvider
|
|
600
634
|
accessToken="YOUR_TOKEN"
|
|
601
|
-
|
|
635
|
+
productId="YOUR_PRODUCT_ID"
|
|
602
636
|
apiConfig={{
|
|
603
637
|
onError: (error) => {
|
|
604
638
|
console.error('kelviq Error:', error);
|
|
@@ -678,7 +712,7 @@ const App: React.FC = () => {
|
|
|
678
712
|
|
|
679
713
|
<KelviqProvider
|
|
680
714
|
accessToken="your-access-token"
|
|
681
|
-
|
|
715
|
+
productId="your-product-id"
|
|
682
716
|
customerId="optional-customer-id"
|
|
683
717
|
checkoutSuccessUrl="https://yourapp.com/success"
|
|
684
718
|
apiConfig={{
|
|
@@ -703,6 +737,7 @@ export default App;
|
|
|
703
737
|
|
|
704
738
|
The SDK uses the following default API endpoints:
|
|
705
739
|
|
|
740
|
+
- **Product Offering API**: `https://api.kelviq.com/api/v1/monetization/product-offering/{productId}/`
|
|
706
741
|
- **Checkout API**: `https://api.kelviq.com/api/v1/checkout/`
|
|
707
742
|
- **Subscription API**: `https://api.kelviq.com/api/v1/subscriptions`
|
|
708
743
|
|
|
@@ -724,7 +759,7 @@ You can override these in the `apiConfig`:
|
|
|
724
759
|
|
|
725
760
|
### Common Issues
|
|
726
761
|
|
|
727
|
-
1. **Loading State**: Ensure your `accessToken` and `
|
|
762
|
+
1. **Loading State**: Ensure your `accessToken` and `productId` are correct
|
|
728
763
|
2. **Styling Issues**: Check CSS variable overrides and custom styles
|
|
729
764
|
3. **API Errors**: Verify API endpoints and network connectivity
|
|
730
765
|
4. **TypeScript Errors**: Ensure all required props are provided
|
|
@@ -739,7 +774,7 @@ Enable console logging for debugging:
|
|
|
739
774
|
onError: (error) => {
|
|
740
775
|
console.log('kelviq Debug:', {
|
|
741
776
|
error: error.message,
|
|
742
|
-
|
|
777
|
+
productId: 'your-product-id',
|
|
743
778
|
timestamp: new Date().toISOString()
|
|
744
779
|
});
|
|
745
780
|
}
|
|
@@ -755,7 +790,7 @@ If you want to use the sandbox, you need to set the `environment` option to `san
|
|
|
755
790
|
```tsx
|
|
756
791
|
<KelviqProvider
|
|
757
792
|
accessToken="YOUR_ACCESS_TOKEN"
|
|
758
|
-
|
|
793
|
+
productId="YOUR_PRODUCT_ID"
|
|
759
794
|
environment="sandbox">
|
|
760
795
|
|
|
761
796
|
</KelviqProvider>
|
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
title: "Fees"
|
|
3
3
|
slug: "getstarted/fees"
|
|
4
4
|
section: "getstarted"
|
|
5
|
-
description: "Kelviq's
|
|
5
|
+
description: "Understand Kelviq's transaction fees and additional charges"
|
|
6
6
|
---
|
|
7
|
-
Kelviq operates as a [Merchant of Record](/getstarted/merchant-of-record), handling payments, tax compliance, and global selling on your behalf.
|
|
7
|
+
Kelviq operates as a [Merchant of Record](/getstarted/merchant-of-record), handling payments, tax compliance, and global selling on your behalf. You pay a transaction fee when a payment succeeds. There are no setup fees, monthly fees, or minimum transaction requirements.
|
|
8
8
|
|
|
9
|
-
## What's
|
|
9
|
+
## What's included
|
|
10
10
|
|
|
11
11
|
Your transaction fee covers everything you need to sell globally:
|
|
12
12
|
|
|
@@ -21,75 +21,66 @@ Your transaction fee covers everything you need to sell globally:
|
|
|
21
21
|
- Feature and entitlement management
|
|
22
22
|
- Customer billing portal
|
|
23
23
|
|
|
24
|
-
## Transaction
|
|
24
|
+
## Transaction fees
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Every successful payment starts with a base fee. The base rate changes after your organization processes $5,000 in total sales volume. A recurring charge or international card can add another percentage to the same transaction.
|
|
27
27
|
|
|
28
|
-
| Fee
|
|
29
|
-
|
|
30
|
-
| Base fee |
|
|
31
|
-
|
|
|
32
|
-
| Recurring billing | +0.7% | Subscription and
|
|
28
|
+
| Fee component | Rate | When it applies |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| Base fee, up to $5,000 in total volume | 2.9% + $0.40 | Successful transactions processed before your organization reaches $5,000 in total sales |
|
|
31
|
+
| Base fee, after $5,000 in total volume | 3.5% + $0.40 | Subsequent successful transactions after your organization reaches $5,000 in total sales |
|
|
32
|
+
| Recurring billing | +0.7% | Subscription payments and renewals |
|
|
33
|
+
| International card | +1.5% | Cards issued outside the United States |
|
|
33
34
|
|
|
34
|
-
|
|
35
|
+
The recurring and international-card percentages are added to the applicable base rate. The fixed $0.40 is charged once per successful transaction.
|
|
35
36
|
|
|
36
|
-
|
|
37
|
+
### How the $5,000 threshold works
|
|
37
38
|
|
|
38
|
-
|
|
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.
|
|
39
40
|
|
|
40
|
-
|
|
41
|
+
The rate change does not alter fees on transactions that were already processed.
|
|
41
42
|
|
|
42
|
-
|
|
43
|
-
|-----------|-------------|--------|
|
|
44
|
-
| Base fee | $100 × 3.5% | $3.50 |
|
|
45
|
-
| Fixed fee | — | $0.40 |
|
|
46
|
-
| **Total fee** | | **$3.90** |
|
|
43
|
+
## All fee combinations
|
|
47
44
|
|
|
48
|
-
|
|
49
|
-
|
|
45
|
+
The additional percentages stack when a charge is both recurring and paid with an international card.
|
|
50
46
|
|
|
51
|
-
|
|
47
|
+
| Transaction type | Up to $5,000 in total volume | After $5,000 in total volume |
|
|
48
|
+
| --- | --- | --- |
|
|
49
|
+
| One-time payment, domestic card | 2.9% + $0.40 | 3.5% + $0.40 |
|
|
50
|
+
| One-time payment, international card | 4.4% + $0.40 | 5.0% + $0.40 |
|
|
51
|
+
| Subscription, domestic card | 3.6% + $0.40 | 4.2% + $0.40 |
|
|
52
|
+
| Subscription, international card | 5.1% + $0.40 | 5.7% + $0.40 |
|
|
52
53
|
|
|
53
|
-
|
|
54
|
+
### Example fees on a $100 charge
|
|
54
55
|
|
|
55
|
-
|
|
56
|
-
|-----------|-------------|--------|
|
|
57
|
-
| Base fee | $100 × 3.5% | $3.50 |
|
|
58
|
-
| Fixed fee | — | $0.40 |
|
|
59
|
-
| International | $100 × 1.5% | $1.50 |
|
|
60
|
-
| **Total fee** | | **$5.40** |
|
|
56
|
+
This example uses a $100 gross charge. If the payment includes tax, the gross amount is the full amount charged to the customer.
|
|
61
57
|
|
|
62
|
-
|
|
63
|
-
|
|
58
|
+
| Transaction type | Fee before the $5,000 threshold | Fee after the $5,000 threshold |
|
|
59
|
+
| --- | ---: | ---: |
|
|
60
|
+
| One-time payment, domestic card | $3.30 | $3.90 |
|
|
61
|
+
| One-time payment, international card | $4.80 | $5.40 |
|
|
62
|
+
| Subscription, domestic card | $4.00 | $4.60 |
|
|
63
|
+
| Subscription, international card | $5.50 | $6.10 |
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
## How fees appear in Transactions
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
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.
|
|
68
68
|
|
|
69
|
-
|
|
70
|
-
|-----------|-------------|--------|
|
|
71
|
-
| Base fee | $50 × 3.5% | $1.75 |
|
|
72
|
-
| Fixed fee | — | $0.40 |
|
|
73
|
-
| Recurring | $50 × 0.7% | $0.35 |
|
|
74
|
-
| **Total fee** | | **$2.50** |
|
|
69
|
+
For a successful transaction:
|
|
75
70
|
|
|
76
|
-
|
|
77
|
-
|
|
71
|
+
```text
|
|
72
|
+
Net = Gross - Fee - Tax
|
|
73
|
+
```
|
|
78
74
|
|
|
79
|
-
|
|
75
|
+
[Learn how to read the Transactions page →](/payouts/transactions)
|
|
80
76
|
|
|
81
|
-
|
|
77
|
+
## Payout fees
|
|
82
78
|
|
|
83
|
-
|
|
84
|
-
|-----------|-------------|--------|
|
|
85
|
-
| Base fee | $50 × 3.5% | $1.75 |
|
|
86
|
-
| Fixed fee | — | $0.40 |
|
|
87
|
-
| International | $50 × 1.5% | $0.75 |
|
|
88
|
-
| Recurring | $50 × 0.7% | $0.35 |
|
|
89
|
-
| **Total fee** | | **$3.25** |
|
|
79
|
+
Currently, Kelviq is bearing the payout fee.
|
|
90
80
|
|
|
91
|
-
|
|
92
|
-
|
|
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.
|
|
82
|
+
|
|
83
|
+
[Learn how Kelviq payouts work →](/payouts/overview)
|
|
93
84
|
|
|
94
85
|
## Refunds
|
|
95
86
|
|
|
@@ -102,7 +93,7 @@ When you issue a refund to a customer, the original transaction fee is **retaine
|
|
|
102
93
|
|
|
103
94
|
Our payment partners charge non-refundable processing fees on the original transaction. We pass this cost structure through to maintain transparent pricing.
|
|
104
95
|
|
|
105
|
-
## Disputes
|
|
96
|
+
## Disputes and chargebacks
|
|
106
97
|
|
|
107
98
|
When a customer disputes a charge with their bank, a **$15 fee** applies regardless of the dispute outcome.
|
|
108
99
|
|
|
@@ -111,7 +102,7 @@ When a customer disputes a charge with their bank, a **$15 fee** applies regardl
|
|
|
111
102
|
| You win | $15 | Returned to you |
|
|
112
103
|
| You lose | $15 | Refunded to customer |
|
|
113
104
|
|
|
114
|
-
### Reducing
|
|
105
|
+
### Reducing disputes
|
|
115
106
|
|
|
116
107
|
|
|
117
108
|
|