@kelviq/mcp-server 0.4.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/README.md +43 -27
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/README.md +16 -0
  6. package/dist/docs/backend-integration/better-auth.md +369 -0
  7. package/dist/docs/backend-integration/node-sdk.md +373 -5
  8. package/dist/docs/backend-integration/python-sdk.md +444 -6
  9. package/dist/docs/changelog/api.md +516 -5
  10. package/dist/docs/changelog/app.md +162 -0
  11. package/dist/docs/changelog/cli.md +33 -0
  12. package/dist/docs/changelog/mcp-server.md +23 -0
  13. package/dist/docs/changelog/node-sdk.md +124 -0
  14. package/dist/docs/changelog/python-sdk.md +135 -0
  15. package/dist/docs/changelog.md +3968 -0
  16. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  17. package/dist/docs/checkout/checkout-configuration.md +88 -22
  18. package/dist/docs/checkout/checkout-metadata.md +219 -0
  19. package/dist/docs/checkout/static-checkout-url.md +201 -0
  20. package/dist/docs/cli/commands.md +1 -1
  21. package/dist/docs/cli/environments.md +17 -9
  22. package/dist/docs/cli/kelviq-config.md +35 -1
  23. package/dist/docs/cli/overview.md +2 -0
  24. package/dist/docs/coustomers-management/overview.md +15 -19
  25. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  26. package/dist/docs/frontend-integration/react-ui.md +51 -16
  27. package/dist/docs/getstarted/fees.md +45 -54
  28. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  29. package/dist/docs/getstarted/review-process.md +3 -3
  30. package/dist/docs/guides/agent-toolkit.md +143 -0
  31. package/dist/docs/guides/mcp-server.md +138 -35
  32. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  33. package/dist/docs/guides/sandbox.md +34 -0
  34. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  35. package/dist/docs/guides/subscription-integration.md +28 -4
  36. package/dist/docs/guides/webhooks.md +367 -6
  37. package/dist/docs/manifest.json +98 -56
  38. package/dist/docs/openapi.json +7411 -2648
  39. package/dist/docs/payouts/overview.md +30 -0
  40. package/dist/docs/payouts/transactions.md +50 -6
  41. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  42. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  43. package/dist/docs/product-catalog/discounts.md +25 -12
  44. package/dist/docs/product-catalog/entitlements.md +53 -16
  45. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  46. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  47. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  48. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  49. package/dist/docs/product-catalog/plans.md +14 -0
  50. package/dist/docs/product-catalog/products.md +5 -13
  51. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  52. package/dist/docs/product-catalog/subscriptions.md +109 -12
  53. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  54. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  55. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  56. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  57. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  58. package/dist/http/client.js +9 -2
  59. package/dist/http/client.js.map +1 -1
  60. package/dist/http/errors.d.ts +8 -0
  61. package/dist/http/errors.js +20 -0
  62. package/dist/http/errors.js.map +1 -1
  63. package/dist/schemas/kelviq.d.ts +199 -0
  64. package/dist/schemas/kelviq.js +173 -0
  65. package/dist/schemas/kelviq.js.map +1 -1
  66. package/dist/server.js +11 -1
  67. package/dist/server.js.map +1 -1
  68. package/dist/tools/discounts.d.ts +3 -0
  69. package/dist/tools/discounts.js +74 -0
  70. package/dist/tools/discounts.js.map +1 -0
  71. package/dist/tools/index.js +4 -0
  72. package/dist/tools/index.js.map +1 -1
  73. package/dist/tools/webhooks.d.ts +10 -0
  74. package/dist/tools/webhooks.js +114 -0
  75. package/dist/tools/webhooks.js.map +1 -0
  76. 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 `license`, `links`, `countries`, and `files` are dropped, with one warning each). Warnings are informational — the file it wrote is still valid.
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
- | `KELVIQ_SANDBOX_SERVER_API_KEY` | Server key for the sandbox environment (the default target). |
61
- | `KELVIQ_SERVER_API_KEY` | Server key for the production environment (`--prod`). |
62
- | `KELVIQ_SANDBOX_BASE_URL` | Override the sandbox API base URL. You almost never need this. |
63
- | `KELVIQ_BASE_URL` | Override the production API base URL. You almost never need this. |
64
- | `KELVIQ_EDGE_URL` | Override the edge API URL. You almost never need this. |
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
- KELVIQ_SANDBOX_SERVER_API_KEY: ${{ secrets.KELVIQ_SANDBOX_SERVER_API_KEY }}
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 variable
80
+ kelviq pull --force # authenticates from the environment variables
76
81
  ```
77
82
 
78
- If a command needs a key and finds none — neither in the environment nor stored — it fails with a message naming the exact variable to set and where to get a key.
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
- **Add a subscription**
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
- <img height="200" src="/images/add-subscription.png" />
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
- 1. Click **Add subscription**.
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
- **Edit a subscription**
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 Your Payment Methods"
2
+ title: "Managing payment methods"
3
3
  slug: "customer-portal/managing-payment-methods"
4
4
  section: "customer-portal"
5
- description: "A guide for managing payment methods for your subscriptions."
5
+ description: "How your customers add, update, and remove payment methods"
6
6
  ---
7
- ## Why Do I Have Multiple Customer Accounts?
7
+ ## Multiple customer records with one email
8
8
 
9
- You might notice that you have multiple customer accounts under your profile, even if you are using a single email address.
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
- When you subscribe to multiple products using the same email address, our system automatically creates a **separate customer ID** for each product subscription. This is intentionally designed so that you can independently manage the payment methods for each individual product—such as setting a default payment method, adding a new payment method, or deleting an existing one.
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
- If you have multiple products managed under the *same* customer ID, those products will be listed together under that specific customer profile.
13
+ ## How Kelviq chooses a payment method
14
14
 
15
- **Key takeaway:** Each separate customer account has its own:
15
+ When a subscription renews, Kelviq first charges the payment method selected when the subscription was created.
16
16
 
17
- * Assigned products and active subscriptions
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
- Make sure you are viewing the correct customer account from your Settings when updating payment methods or checking your subscription statuses.
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
- ### Default Payment Method
23
+ Paying an invoice manually does not turn off automatic payments. The customer's payment authorization remains active for future renewals.
30
24
 
31
- In your Billing Settings, you can add multiple payment methods (such as credit cards, Amazon pay, Link, UPI etc.. ) and designate one as your **Default Payment Method**.
25
+ See [Failed subscription payments](/product-catalog/subscriptions#failed-subscription-payments) for the card retry schedule.
32
26
 
33
- ### How the Fallback Works
27
+ ## How customers manage payment methods
34
28
 
35
- When a subscription renews or an automatic charge occurs, the system will primarily attempt to charge the payment method that was selected at the time of subscription.
29
+ ### Add a payment method
36
30
 
37
- However, if the primary payment method used for the subscription fails (e.g., due to an expired card, insufficient funds, or a processing error), the system will automatically use your **Saved Default Payment Method** as a fallback.
38
-
39
- This fallback mechanism ensures that your subscription remains active and you do not experience any disruption in service.
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
- ## Managing Your Payment Methods
36
+ The new payment method appears under **Saved payment methods**.
44
37
 
45
- Below are detailed instructions on how to keep your billing information up to date across your customer accounts.
38
+ ### Set the default payment method
46
39
 
47
- ### Adding a Payment Method
40
+ The default payment method is used as a fallback if the payment method attached to a subscription fails.
48
41
 
49
- You can add multiple payment methods to ensure you always have a valid card on file for your subscriptions.
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
- 1. Navigate to **Settings** from the main menu and select the **Billing** tab.
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
- ### Deleting a Payment Method
48
+ ### Delete a payment method
67
49
 
68
- If a card has expired or you no longer want to use it for future billing, you can easily remove it. *Note: You cannot delete a card that is currently set as your default payment method.*
50
+ Customers cannot delete their current default payment method. They must set another payment method as the default first.
69
51
 
70
- 1. Navigate to **Settings** > **Billing**.
71
- 2. Locate the saved card you want to remove.
72
- 3. Click the **trash can icon** next to the payment method to remove payment method from your account.
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.