@kelviq/mcp-server 0.3.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 +37 -30
- package/dist/config.d.ts +5 -0
- package/dist/config.js +31 -10
- 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 +84 -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 +134 -63
- 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 +109 -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/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -0
- package/dist/schemas/kelviq.js +50 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +15 -3
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +3 -0
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +8 -0
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.js +1 -0
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +5 -0
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +5 -1
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Customize a static checkout URL"
|
|
3
|
+
slug: "checkout/static-checkout-url"
|
|
4
|
+
section: "checkout"
|
|
5
|
+
description: "Choose plans, set a billing period, attach a customer, apply a discount, and control the success redirect in a Kelviq checkout link"
|
|
6
|
+
---
|
|
7
|
+
A static checkout URL is a shareable link for one published product. You can use the link exactly as Kelviq generates it, or add query parameters to control what the customer sees when checkout opens.
|
|
8
|
+
|
|
9
|
+
Static links work well on pricing pages, in emails, and behind a purchase button. If the checkout needs data that only your backend knows, use the [Checkout API](/api-reference/checkout/create-a-checkout-session) instead.
|
|
10
|
+
|
|
11
|
+
## Copy the checkout URL
|
|
12
|
+
|
|
13
|
+
1. Open **Product Catalog → Products**.
|
|
14
|
+
2. Select a published product.
|
|
15
|
+
3. Click **Get link** or **Copy checkout link**.
|
|
16
|
+
4. Choose the plans and default billing period.
|
|
17
|
+
5. Copy the generated URL.
|
|
18
|
+
|
|
19
|
+
Production links use this format:
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
https://www.kelviq.com/buy/{PRODUCT_UUID}/
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Sandbox links include `/sandbox/`:
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The product UUID is part of the copied link. Do not replace it with the old product identifier.
|
|
32
|
+
|
|
33
|
+
## Available query parameters
|
|
34
|
+
|
|
35
|
+
The dashboard adds the plan, billing-period, and discount options you select. You can add `customer_id` and `success_url` when your integration needs them.
|
|
36
|
+
|
|
37
|
+
| Parameter | Value | What it changes |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| `enabled` | Comma-separated plan identifiers | Limits checkout to the listed plans |
|
|
40
|
+
| `plan_identifier` | One plan identifier | Selects the plan shown first |
|
|
41
|
+
| `charge_period` | A supported billing-period value | Selects the initial billing period |
|
|
42
|
+
| `discounts_enabled` | `true` or `false` | Shows or hides discount-code entry |
|
|
43
|
+
| `discount_code` | An active discount code | Applies the code when checkout opens |
|
|
44
|
+
| `customer_id` | Your unique customer ID | Links checkout to a specific customer record |
|
|
45
|
+
| `success_url` | A URL-encoded URL | Redirects the customer after successful checkout |
|
|
46
|
+
|
|
47
|
+
Use these values for `charge_period`:
|
|
48
|
+
|
|
49
|
+
| Value | Billing period |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `ONE_TIME` | One-time payment |
|
|
52
|
+
| `DAILY` | Daily |
|
|
53
|
+
| `WEEKLY` | Weekly |
|
|
54
|
+
| `TWENTY_EIGHT_DAYS` | Every 28 days |
|
|
55
|
+
| `MONTHLY` | Monthly |
|
|
56
|
+
| `THREE_MONTHS` | Every three months |
|
|
57
|
+
| `SIX_MONTHS` | Every six months |
|
|
58
|
+
| `YEARLY` | Yearly |
|
|
59
|
+
|
|
60
|
+
The selected plan must support the selected period. If you use `enabled`, include the value from `plan_identifier` in that list.
|
|
61
|
+
|
|
62
|
+
## Build a link safely
|
|
63
|
+
|
|
64
|
+
Use `?` before the first query parameter and `&` before each additional parameter:
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
https://www.kelviq.com/buy/{PRODUCT_UUID}/?enabled=starter,pro&plan_identifier=pro&charge_period=MONTHLY
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Using `URL` and `URLSearchParams` is safer than joining strings by hand. It handles characters that must be encoded:
|
|
71
|
+
|
|
72
|
+
```javascript
|
|
73
|
+
const checkoutUrl = new URL(
|
|
74
|
+
"https://www.kelviq.com/buy/{PRODUCT_UUID}/",
|
|
75
|
+
);
|
|
76
|
+
|
|
77
|
+
checkoutUrl.searchParams.set("enabled", "starter,pro");
|
|
78
|
+
checkoutUrl.searchParams.set("plan_identifier", "pro");
|
|
79
|
+
checkoutUrl.searchParams.set("charge_period", "MONTHLY");
|
|
80
|
+
checkoutUrl.searchParams.set("discounts_enabled", "true");
|
|
81
|
+
checkoutUrl.searchParams.set("discount_code", "LAUNCH20");
|
|
82
|
+
checkoutUrl.searchParams.set("customer_id", "cust_789");
|
|
83
|
+
checkoutUrl.searchParams.set(
|
|
84
|
+
"success_url",
|
|
85
|
+
"https://example.com/checkout/success",
|
|
86
|
+
);
|
|
87
|
+
|
|
88
|
+
console.log(checkoutUrl.toString());
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The resulting URL is equivalent to:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
https://www.kelviq.com/buy/{PRODUCT_UUID}/?enabled=starter%2Cpro&plan_identifier=pro&charge_period=MONTHLY&discounts_enabled=true&discount_code=LAUNCH20&customer_id=cust_789&success_url=https%3A%2F%2Fexample.com%2Fcheckout%2Fsuccess
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Common configurations
|
|
98
|
+
|
|
99
|
+
### Select a plan and billing period
|
|
100
|
+
|
|
101
|
+
Show the Starter and Pro plans, with Pro monthly selected when checkout opens:
|
|
102
|
+
|
|
103
|
+
```text
|
|
104
|
+
?enabled=starter,pro&plan_identifier=pro&charge_period=MONTHLY
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Hide discount-code entry
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
?discounts_enabled=false
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`discounts_enabled` defaults to `true`.
|
|
114
|
+
|
|
115
|
+
### Apply a discount code
|
|
116
|
+
|
|
117
|
+
```text
|
|
118
|
+
?discounts_enabled=true&discount_code=LAUNCH20
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The discount must be active and valid for the selected product, plan, currency, and date. [Learn how checkout discounts work →](/checkout/apply-a-discount-code)
|
|
122
|
+
|
|
123
|
+
### Link checkout to a customer
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
?customer_id=cust_789
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Use the stable, unique customer ID from your application. When the customer record already has an email address, Kelviq can prefill it at checkout.
|
|
130
|
+
|
|
131
|
+
A customer-specific URL should not be published as a general checkout link. Query parameters can appear in browser history, analytics, and server logs. Use an opaque customer ID and never put an email address, API key, or secret in the URL.
|
|
132
|
+
|
|
133
|
+
### Redirect after successful checkout
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
?success_url=https%3A%2F%2Fexample.com%2Fcheckout%2Fsuccess
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Encode the full destination URL. In JavaScript, `URLSearchParams` does this for you. In other environments, use the standard URL-encoding function provided by the language or framework.
|
|
140
|
+
|
|
141
|
+
A visit to `success_url` is not proof of payment. Customers can open that page directly. Confirm payment through `checkout.completed`, the resulting subscription or order, or a current entitlement check.
|
|
142
|
+
|
|
143
|
+
## Static URL names and API names
|
|
144
|
+
|
|
145
|
+
Static checkout links use snake_case query parameters. The Checkout API and backend SDKs use camelCase request fields.
|
|
146
|
+
|
|
147
|
+
| Static URL | Checkout API or SDK |
|
|
148
|
+
| --- | --- |
|
|
149
|
+
| `enabled` | `plansEnabled` |
|
|
150
|
+
| `plan_identifier` | `planIdentifier` |
|
|
151
|
+
| `charge_period` | `chargePeriod` |
|
|
152
|
+
| `discounts_enabled` | `discountsEnabled` |
|
|
153
|
+
| `discount_code` | `discountCode` |
|
|
154
|
+
| `customer_id` | `customerId` |
|
|
155
|
+
| `success_url` | `successUrl` |
|
|
156
|
+
|
|
157
|
+
Do not put camelCase names into the URL. For example, `successUrl` belongs in an API request; `success_url` belongs in a static checkout URL.
|
|
158
|
+
|
|
159
|
+
## When to use the Checkout API
|
|
160
|
+
|
|
161
|
+
Use the Checkout API or a backend SDK when you need per-session options that are not part of the static URL contract, including:
|
|
162
|
+
|
|
163
|
+
- a cancellation URL;
|
|
164
|
+
- feature quantities;
|
|
165
|
+
- location-based pricing through the customer's IP address;
|
|
166
|
+
- custom amounts, currency, or tax behavior;
|
|
167
|
+
- a locked email or default billing country; or
|
|
168
|
+
- checkout metadata for webhook correlation.
|
|
169
|
+
|
|
170
|
+
The API creates a short-lived checkout session and returns `checkoutUrl` and `checkoutSessionId`. Keep the server API key on your backend.
|
|
171
|
+
|
|
172
|
+
[Create a checkout session with the API →](/api-reference/checkout/create-a-checkout-session)
|
|
173
|
+
|
|
174
|
+
## Test the link
|
|
175
|
+
|
|
176
|
+
1. Enter sandbox mode and copy a sandbox checkout link.
|
|
177
|
+
2. Add one customization at a time.
|
|
178
|
+
3. Open the link and confirm the visible plans, selected period, discount behavior, and customer details.
|
|
179
|
+
4. Complete a sandbox checkout.
|
|
180
|
+
5. Confirm the success redirect and the `checkout.completed` webhook.
|
|
181
|
+
|
|
182
|
+
Keep sandbox products, customers, discounts, and API credentials together. A live customer ID or discount code will not work against a sandbox checkout.
|
|
183
|
+
|
|
184
|
+
## Troubleshooting
|
|
185
|
+
|
|
186
|
+
| Problem | Check |
|
|
187
|
+
| --- | --- |
|
|
188
|
+
| A parameter is ignored | Match the snake_case name exactly. Query parameter names are case-sensitive. |
|
|
189
|
+
| The wrong billing period opens | Use an uppercase value such as `MONTHLY`, and confirm that the selected plan supports it. |
|
|
190
|
+
| The default plan is not available | Add that plan identifier to `enabled`, or remove `enabled` to show every available plan. |
|
|
191
|
+
| The success URL breaks the checkout link | URL-encode the complete value instead of inserting an unescaped URL. |
|
|
192
|
+
| A discount does not apply | Check its status, dates, redemption limit, product and plan restrictions, and currency. |
|
|
193
|
+
| The wrong customer is selected | Check `customer_id` and make sure the customer exists in the same environment as the checkout link. |
|
|
194
|
+
| A sandbox link cannot find live data | Create or select the matching record in sandbox. Sandbox and production data are separate. |
|
|
195
|
+
|
|
196
|
+
## Related documentation
|
|
197
|
+
|
|
198
|
+
- [Checkout configuration](/checkout/checkout-configuration)
|
|
199
|
+
- [Apply a discount code at checkout](/checkout/apply-a-discount-code)
|
|
200
|
+
- [Add metadata to checkout](/checkout/checkout-metadata)
|
|
201
|
+
- [Webhooks](/guides/webhooks)
|
|
@@ -117,7 +117,7 @@ kelviq pull --force # overwrite an existing file
|
|
|
117
117
|
|
|
118
118
|
What it fetches: all products, all features, the **latest version** of each plan, and each plan's prices and entitlements. Every cross-reference in the generated file uses `identifier` slugs, never UUIDs — the file is stable across environments that share identifiers.
|
|
119
119
|
|
|
120
|
-
On success, `pull` prints the path it wrote and a **warnings list** for anything it couldn't represent in the config format (for example, plan fields like `
|
|
120
|
+
On success, `pull` prints the path it wrote and a **warnings list** for anything it couldn't represent in the config format (for example, plan fields like `links`, `countries`, and `files` are dropped, with one warning each; a plan's `license` settings are pulled into the file). Warnings are informational — the file it wrote is still valid.
|
|
121
121
|
|
|
122
122
|
On failure — missing key, network error, unexpected API response — `pull` writes `pull failed: <reason>` to stderr and exits non-zero without touching the output file.
|
|
123
123
|
|
|
@@ -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.
|