@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.
Files changed (63) hide show
  1. package/README.md +34 -26
  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/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +23 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +114 -34
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +102 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/server.js +10 -1
  62. package/dist/server.js.map +1 -1
  63. 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
- | `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.
@@ -36,7 +36,7 @@ function App() {
36
36
  return (
37
37
  <KelviqProvider
38
38
  accessToken="YOUR_ACCESS_TOKEN"
39
- offeringId="YOUR_OFFERING_ID"
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
- offeringId="YOUR_OFFERING_ID"
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 client access token |
85
- | `offeringId` | `string` | The unique identifier for your offering |
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` | `{}` | Custom styling configuration |
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
- | `pricingTable` | `PricingTable` | Yes | Pricing table configuration |
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
- | `pricingTable` | `PricingTable` | Yes | Pricing table configuration |
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. Custom Action Button
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.4. noStyles Mode
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.5. CSS Class Reference
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
- offeringId="YOUR_OFFERING"
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
- offeringId="your-offering-id"
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 `offeringId` are correct
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
- offeringId: 'your-offering-id',
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
- offeringId="YOUR_OFFERING_ID"
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 transparent pricing structure"
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. Our pricing is simple and all-inclusive—no hidden fees, no monthly minimums.
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 Included
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 Fees
24
+ ## Transaction fees
25
25
 
26
- Fees are charged only on successful transactions:
26
+ Every successful payment starts with a base fee. The base rate changes after your organization processes &#36;5,000 in total sales volume. A recurring charge or international card can add another percentage to the same transaction.
27
27
 
28
- | Fee Type | Rate | Description |
29
- |----------|------|-------------|
30
- | Base fee | 3.5% + $0.40 | Applied to every transaction |
31
- | International cards | +1.5% | Cards issued outside the US |
32
- | Recurring billing | +0.7% | Subscription and renewal charges |
28
+ | Fee component | Rate | When it applies |
29
+ | --- | --- | --- |
30
+ | Base fee, up to &#36;5,000 in total volume | 2.9% + &#36;0.40 | Successful transactions processed before your organization reaches &#36;5,000 in total sales |
31
+ | Base fee, after &#36;5,000 in total volume | 3.5% + &#36;0.40 | Subsequent successful transactions after your organization reaches &#36;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
- Fees are calculated on the transaction amount before tax.
35
+ The recurring and international-card percentages are added to the applicable base rate. The fixed &#36;0.40 is charged once per successful transaction.
35
36
 
36
- ## Fee Examples
37
+ ### How the &#36;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% + &#36;0.40 on transactions processed before reaching &#36;5,000. After your total processed volume reaches &#36;5,000, subsequent transactions use the 3.5% + &#36;0.40 base rate.
39
40
 
40
- **$100 product, US customer, US-issued card**
41
+ The rate change does not alter fees on transactions that were already processed.
41
42
 
42
- | Component | Calculation | Amount |
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
- You receive: $96.10
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 &#36;5,000 in total volume | After &#36;5,000 in total volume |
48
+ | --- | --- | --- |
49
+ | One-time payment, domestic card | 2.9% + &#36;0.40 | 3.5% + &#36;0.40 |
50
+ | One-time payment, international card | 4.4% + &#36;0.40 | 5.0% + &#36;0.40 |
51
+ | Subscription, domestic card | 3.6% + &#36;0.40 | 4.2% + &#36;0.40 |
52
+ | Subscription, international card | 5.1% + &#36;0.40 | 5.7% + &#36;0.40 |
52
53
 
53
- **$100 product, UK customer, UK-issued card**
54
+ ### Example fees on a &#36;100 charge
54
55
 
55
- | Component | Calculation | Amount |
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 &#36;100 gross charge. If the payment includes tax, the gross amount is the full amount charged to the customer.
61
57
 
62
- You receive: $94.60
63
-
58
+ | Transaction type | Fee before the &#36;5,000 threshold | Fee after the &#36;5,000 threshold |
59
+ | --- | ---: | ---: |
60
+ | One-time payment, domestic card | &#36;3.30 | &#36;3.90 |
61
+ | One-time payment, international card | &#36;4.80 | &#36;5.40 |
62
+ | Subscription, domestic card | &#36;4.00 | &#36;4.60 |
63
+ | Subscription, international card | &#36;5.50 | &#36;6.10 |
64
64
 
65
-
65
+ ## How fees appear in Transactions
66
66
 
67
- **$50/month subscription, US customer, US-issued card**
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
- | Component | Calculation | Amount |
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
- You receive: $47.50 per month
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
- **$50/month subscription, German customer, German-issued card**
77
+ ## Payout fees
82
78
 
83
- | Component | Calculation | Amount |
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
- You receive: $46.75 per month
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 & Chargebacks
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 Disputes
105
+ ### Reducing disputes
115
106
 
116
107
 
117
108