@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.
Files changed (103) hide show
  1. package/README.md +37 -30
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +31 -10
  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 +84 -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 +134 -63
  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 +109 -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/prompts/index.d.ts +2 -0
  62. package/dist/prompts/index.js +107 -0
  63. package/dist/prompts/index.js.map +1 -0
  64. package/dist/schemas/kelviq.d.ts +30 -0
  65. package/dist/schemas/kelviq.js +50 -0
  66. package/dist/schemas/kelviq.js.map +1 -1
  67. package/dist/server.js +15 -3
  68. package/dist/server.js.map +1 -1
  69. package/dist/tools/checkout.js +2 -1
  70. package/dist/tools/checkout.js.map +1 -1
  71. package/dist/tools/customers.js +2 -0
  72. package/dist/tools/customers.js.map +1 -1
  73. package/dist/tools/docs.js +2 -0
  74. package/dist/tools/docs.js.map +1 -1
  75. package/dist/tools/entitlements.js +1 -0
  76. package/dist/tools/entitlements.js.map +1 -1
  77. package/dist/tools/features.js +4 -0
  78. package/dist/tools/features.js.map +1 -1
  79. package/dist/tools/licenses.js +3 -0
  80. package/dist/tools/licenses.js.map +1 -1
  81. package/dist/tools/offerings.js +1 -0
  82. package/dist/tools/offerings.js.map +1 -1
  83. package/dist/tools/plan-entitlements.js +4 -0
  84. package/dist/tools/plan-entitlements.js.map +1 -1
  85. package/dist/tools/plan-files.js +3 -0
  86. package/dist/tools/plan-files.js.map +1 -1
  87. package/dist/tools/plans.js +8 -0
  88. package/dist/tools/plans.js.map +1 -1
  89. package/dist/tools/portal.js +1 -0
  90. package/dist/tools/portal.js.map +1 -1
  91. package/dist/tools/product-files.js +2 -0
  92. package/dist/tools/product-files.js.map +1 -1
  93. package/dist/tools/product-settings.js +2 -0
  94. package/dist/tools/product-settings.js.map +1 -1
  95. package/dist/tools/products.js +5 -0
  96. package/dist/tools/products.js.map +1 -1
  97. package/dist/tools/promotions.js +1 -0
  98. package/dist/tools/promotions.js.map +1 -1
  99. package/dist/tools/subscriptions.js +5 -1
  100. package/dist/tools/subscriptions.js.map +1 -1
  101. package/dist/tools/usage.js +1 -0
  102. package/dist/tools/usage.js.map +1 -1
  103. package/package.json +1 -1
@@ -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
 
@@ -0,0 +1,98 @@
1
+ ---
2
+ title: "Payment security and seller funds"
3
+ slug: "getstarted/payment-security-and-seller-funds"
4
+ section: "getstarted"
5
+ description: "How Kelviq protects card details, routes payments through Stripe, and handles payouts, account reviews, and migrations"
6
+ ---
7
+ When a customer buys through Kelviq Checkout, Kelviq is the Merchant of Record and Stripe processes the payment. The customer's raw card details go directly to Stripe through secure payment fields; they are not passed to Kelviq or your connected account. Stripe also provides the connected account used for your payouts. Here is how payment data, money, and subscription records move at each stage.
8
+
9
+ This page is an operational overview. If it conflicts with the [Seller Agreement](/legal/master-service-agreement), the agreement controls.
10
+
11
+ ## How does a payment move?
12
+
13
+
14
+
15
+ Kelviq Checkout uses [Stripe Elements](https://docs.stripe.com/payments/elements). Stripe tokenizes sensitive payment details in the browser, so the full card number and CVC do not pass through or get stored on Kelviq's servers.
16
+
17
+
18
+
19
+
20
+ The charge and its PaymentIntent are created on Kelviq's Stripe platform account because Kelviq is the Merchant of Record.
21
+
22
+
23
+
24
+
25
+ Kelviq accounts for applicable taxes, platform fees, refunds, and other adjustments before calculating your net revenue.
26
+
27
+
28
+
29
+
30
+ Kelviq creates a separate transfer to your Stripe Express connected account. The funds appear there after Stripe makes them available.
31
+
32
+
33
+
34
+
35
+ You can withdraw cleared funds to the bank account attached to your connected account.
36
+
37
+
38
+ Kelviq uses Stripe Connect's **separate charges and transfers** model. It does not use direct charges or destination charges. See the [full payment flow](/legal/payment-flow-diagram) for the technical breakdown.
39
+
40
+ ## Who handles the card details?
41
+
42
+ The checkout may carry Kelviq's design, but Stripe provides the sensitive payment fields. Stripe.js tokenizes the details inside those fields and returns identifiers Kelviq can use to complete the payment. Kelviq receives the payment result, not the customer's full card number or CVC.
43
+
44
+ Stripe can also request 3D Secure authentication when it is required by the card issuer or recommended for fraud prevention. This adds an identity check without exposing the customer's card details to Kelviq.
45
+
46
+ Banks can still decline or reverse a payment, customers can open disputes, and Stripe or a card network can request a review. Kelviq handles those events as the Merchant of Record.
47
+
48
+ ## Where does the money actually sit?
49
+
50
+ During processing, the money appears in Stripe balances. It first appears in Kelviq's Stripe platform balance. After the separate transfer, your share appears in your Stripe connected-account balance. Stripe then sends the payout to your registered bank account.
51
+
52
+ A Kelviq payout balance is not a bank deposit, escrow account, or insured investment. It represents amounts due under the Seller Agreement and can change because of refunds, chargebacks, fees, currency conversion, or a valid reserve.
53
+
54
+ You can track this flow in two places:
55
+
56
+ - The Kelviq **Payouts** dashboard shows processing funds, cleared funds, withdrawals, and payout history.
57
+ - Your Stripe connected-account details show the verified business and bank account used for payouts.
58
+
59
+ Read [Payouts](/payouts/overview) for the dashboard workflow.
60
+
61
+ ## What protects my funds if Kelviq closes my account?
62
+
63
+ The Seller Agreement sets out Kelviq's payout obligations and when a payout can be delayed or reserved:
64
+
65
+ - Completed transactions move to your available balance after processing.
66
+ - Final payouts remain due if Kelviq ends the service, subject to open disputes and a permitted reserve.
67
+ - A reserve must have a stated amount or percentage and an expected duration.
68
+ - A post-termination reserve can remain in place for up to 180 days to cover refunds, chargebacks, or other transaction liabilities.
69
+
70
+ This is not a guarantee that nothing can go wrong. A processor failure, bank delay, dispute, compliance action, or insolvency can still affect the timing or recovery of funds. What you do have is a written payment flow, transaction records, and contractual payout terms against which you can check Kelviq's handling of your money. Review [Payout Terms](/legal/master-service-agreement#7-payout-terms) and [Reserves and Holdbacks](/legal/master-service-agreement#8-reserves-and-holdbacks) for the controlling language.
71
+
72
+ ## How much notice will I get before a suspension?
73
+
74
+ There is no single advance-notice period for every suspension, including every non-fraud suspension. Kelviq may need to act quickly because of suspected fraud, prohibited activity, failed verification, a legal requirement, a payment-network instruction, or a restriction on the connected Stripe account.
75
+
76
+ The 30-day notice in the Seller Agreement applies when Kelviq terminates an account for convenience. It does not apply to the grounds for immediate termination listed in that agreement. If you believe a policy suspension or termination was made in error, you can appeal it. Kelviq responds to appeals within 10 business days under the [Acceptable Use Policy](/legal/approved-prohibited-policy#83-appeal-process).
77
+
78
+ ### Will my customers' subscriptions cancel immediately?
79
+
80
+ Not in every case. A suspension and a subscription cancellation are separate actions. However, Kelviq may need to block checkout or future renewals, depending on why the account was restricted. The Seller Agreement does not promise uninterrupted subscription collection during a suspension. If a notice does not clearly say which functions are affected, contact [support@kelviq.com](mailto:support@kelviq.com) before making changes for your customers.
81
+
82
+ ## Where do the Stripe Customer and Subscription records live?
83
+
84
+ Kelviq manages the buyer-facing Stripe Customer, PaymentIntent, invoice, and Subscription records on its Stripe platform account. Your Stripe Express connected account receives transfers and payouts; it does not receive an independent copy of every platform billing object.
85
+
86
+ An ID such as `cus_...` or `sub_...` points to an object inside the Stripe account where it was created. It cannot simply be reassigned to another Stripe account. Under the [Seller Agreement](/legal/master-service-agreement#111-buyer-data), Kelviq controls buyer payment and transaction data in its role as Merchant of Record. You still own your product and content, and Kelviq provides the buyer information needed for fulfillment and customer support.
87
+
88
+ ## Can I move to another provider?
89
+
90
+ A billing migration is possible in some cases, but it is not an automatic account transfer. Contact [support@kelviq.com](mailto:support@kelviq.com) before closing your Kelviq account or disconnecting Stripe. Kelviq will review the request with Stripe and the receiving provider, then explain what can be transferred.
91
+
92
+ Stripe supports secure exports of eligible card data to a PCI DSS Level 1 payment processor. Some credentials, including cards saved through Link, cannot be exported. Subscription records and payment history also need to be mapped or recreated in the new billing system; moving card data alone does not move an active subscription.
93
+
94
+ Migration scope and timing depend on the receiving provider, Stripe's requirements, applicable privacy rules, and any unresolved refunds, disputes, or reserves. See [Stripe's payment-data export process](https://docs.stripe.com/get-started/data-migrations/pan-export) for the processor-level requirements.
95
+
96
+ ## Questions about your account
97
+
98
+ For an account-specific explanation of a payout, reserve, suspension, or migration, email [support@kelviq.com](mailto:support@kelviq.com). Include your Kelviq business name and the relevant transaction, payout, or subscription IDs, but never send a full card number or CVC.
@@ -132,11 +132,11 @@ There are two steps to complete before you can start accepting real payments:
132
132
 
133
133
  ### Step 1: Business Verification
134
134
 
135
- You'll see a **Business Verification** prompt in the sidebar of your dashboard. Click **Start verification** to begin.
135
+ Open **Settings → Business details** in the Kelviq dashboard. You can also continue from the business-verification prompt shown during onboarding.
136
136
 
137
- <img src="/images/review-process/business-verification-prompt.png" alt="Business Verification prompt in sidebar" />
137
+ <img src="/images/review-process/business-verification-prompt.png" alt="Business verification prompt shown during onboarding" />
138
138
 
139
- Fill in your business details and click **Submit for review** when you're done.
139
+ Fill in your business details and click **Submit for review** when you're done. Kelviq places the country from your organization profile first in the country selector to make it easier to find. Review the country before submitting the form.
140
140
 
141
141
  <img src="/images/review-process/business-details-form.png" alt="Business details form" />
142
142
 
@@ -0,0 +1,143 @@
1
+ ---
2
+ title: "Agent Toolkit"
3
+ slug: "guides/agent-toolkit"
4
+ section: "guides"
5
+ description: "Install Kelviq into Claude Code with one plugin — or add the Kelviq skills to any of 70+ AI coding agents."
6
+ ---
7
+ The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus five **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
8
+
9
+ Skills are the missing half of tool access. The MCP server gives your agent 45 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
10
+
11
+ **The Agent Toolkit is new.** The skills and their names are stable, but content will keep improving alongside the platform. The bundled MCP server is always the latest published `@kelviq/mcp-server` — no toolkit update needed when the server improves.
12
+
13
+ ---
14
+
15
+ ## Install — Claude Code
16
+
17
+ Two commands, in any Claude Code session:
18
+
19
+ ```
20
+ /plugin marketplace add kelviq/agent-toolkit
21
+ /plugin install kelviq@kelviq
22
+ ```
23
+
24
+ This installs the full bundle: the MCP server is configured for you (no `claude mcp add`, no `--` separator gotchas) and all five skills are available immediately.
25
+
26
+ The server reads your API keys from environment variables. It uses your **sandbox** environment unless `KELVIQ_ENV=production`, so start with sandbox keys. Set them in your shell profile before starting Claude Code:
27
+
28
+ ```bash
29
+ export KELVIQ_SERVER_API_KEY="<your-sandbox-server-key>"
30
+ export KELVIQ_CLIENT_API_KEY="<your-sandbox-client-key>" # only needed for promotion_get
31
+ ```
32
+
33
+ Get keys at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
34
+
35
+ **Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 45 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
36
+
37
+ No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work without any credentials, so your agent can answer Kelviq questions from the documentation immediately. API tools return a clear `Configuration error` until a key is set.
38
+
39
+ ---
40
+
41
+ ## Install — any other agent
42
+
43
+ The five skills are also published through the open skills ecosystem, installable into 70+ agents (Cursor, Codex, GitHub Copilot, OpenCode, Zed, and more):
44
+
45
+ ```bash
46
+ npx skills add kelviq/agent-toolkit
47
+ ```
48
+
49
+ Add `--skill <name>` to install a single skill instead of the full set:
50
+
51
+ ```bash
52
+ npx skills add kelviq/agent-toolkit --skill setup-payments
53
+ ```
54
+
55
+ This path installs **skills only** — it doesn't configure an MCP server for you. Each skill starts with a short Setup section showing the `.mcp.json` snippet to connect `@kelviq/mcp-server` on your agent; see the [MCP server guide](/guides/mcp-server) for client-specific instructions.
56
+
57
+ ---
58
+
59
+ ## The five skills
60
+
61
+ | Skill | What it teaches |
62
+ |---|---|
63
+ | `kelviq` | The hub. Connecting any agent to Kelviq, the ground rules (docs-first, error handling, confirm-before-destructive), the concept model (identifiers vs UUIDs, feature types, plan lifecycle, environments), and routing to the right skill or prompt for the task. |
64
+ | `pricing-plans` | Designing and publishing the catalog: products, features, plans, entitlements, the DRAFT → publish lifecycle, and customer-migration decisions on publish. |
65
+ | `setup-payments` | Selling plans and managing subscribers: checkout sessions, subscriptions, trials, upgrades, cancellation, and authenticated customer portal links. |
66
+ | `usage-based-billing` | Enforcing what was sold: runtime entitlement checks served from the edge, safe usage reporting for metered features, and the license key lifecycle. |
67
+ | `pricing-as-code` | The [Kelviq CLI](/cli/overview) workflow: pull the live catalog into `kelviq.config.ts`, edit in git, preview the diff, apply, and promote sandbox to production. |
68
+
69
+ ### `kelviq` — the hub
70
+
71
+ Loads for any Kelviq task that doesn't match a more specific skill. It carries the knowledge every other skill assumes:
72
+
73
+ - **Identifiers vs UUIDs** — when an endpoint wants the URL-safe `identifier` and when it wants the UUID, and how to resolve one from the other.
74
+ - **Feature types** — `BOOLEAN` (flag), `CUSTOMIZABLE` (numeric quantity), `METER` (usage-tracked), and how entitlement shapes differ per type.
75
+ - **Plan lifecycle** — plans are created in DRAFT and invisible until published; updating a published plan creates a new draft.
76
+ - **Environments** — sandbox by default, `KELVIQ_ENV=production` only for live data, and why "not found" errors often mean "right key, wrong environment".
77
+ - **A customer-access diagnosis flow** — comparing what a customer *has* (`entitlements_get`), what they *bought* (`subscription_list`), and what their plan *grants* (`plan_entitlements_list`).
78
+
79
+ ### `pricing-plans`
80
+
81
+ The golden path from empty account to published plan: create the product, create the features, create the plan (in DRAFT), attach entitlements, set prices, publish, verify. Includes the two decisions agents most often get wrong: whether to migrate existing customers on publish (`updateFeatures` / `updatePricing` — always a deliberate, confirmed choice), and where prices are managed (the dashboard or the CLI — the MCP server deliberately has no price-write tool).
82
+
83
+ ### `setup-payments`
84
+
85
+ Checkout-first selling. The skill teaches that `checkout_create_session` is the default way to charge a customer — direct subscription creation charges off-session and is only enabled for some organizations — plus trial handling (`trialEnd`), safe plan changes (`paymentBehavior`), cancellation types, and the customer portal (always the signed URL from `portal_session_create`; a bare portal URL doesn't authenticate).
86
+
87
+ ### `usage-based-billing`
88
+
89
+ Runtime enforcement. Entitlement checks via the edge-served `entitlements_get` (built to be cheap enough to call on the request path), the difference between `SET` and `DELTA` usage reporting — and why a blindly retried `DELTA` double-counts — plus license key activation, validation, and deactivation with `instanceId` handling.
90
+
91
+ ### `pricing-as-code`
92
+
93
+ Wraps the [Kelviq CLI](/cli/overview) loop for agents: `kelviq pull` → edit `kelviq.config.ts` in a branch → `kelviq push --dry-run` → review → apply → `kelviq promote` from sandbox to production. The skill has a built-in safety rule: an agent may run dry-runs and show you diffs freely, but **applying a real change always requires your explicit approval** — it will never chain a dry-run into an unattended `--yes`.
94
+
95
+ ---
96
+
97
+ ## Skills, prompts, and tools — how they fit
98
+
99
+ The toolkit layers three things, each doing what it's best at:
100
+
101
+ 1. **Tools** (from the MCP server) do the work — 45 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
102
+ 2. **Skills** (from this toolkit) supply the judgment — which tool, in what order, with which confirmations. They activate automatically based on what you ask.
103
+ 3. **Prompts** (from the MCP server) are guided, step-by-step flows you invoke explicitly — `setup_product`, `launch_plan`, and `diagnose_customer`. The skills route to them rather than duplicating them.
104
+
105
+ Deep reference detail (field lists, price shapes, config schemas) intentionally lives in none of these — the skills direct the agent to `docs_search` / `docs_read`, so answers always come from the current documentation.
106
+
107
+ ---
108
+
109
+ ## Sandbox and production
110
+
111
+ The bundled server uses your **sandbox** environment unless you set `KELVIQ_ENV=production` — separate data, separate keys, nothing crosses between them. Build and test in sandbox, and switch to production (with production API keys) only when you want the agent to work with live data. See the [sandbox guide](/guides/sandbox) for details.
112
+
113
+ ```bash
114
+ export KELVIQ_ENV="production"
115
+ export KELVIQ_SERVER_API_KEY="<your-production-server-key>"
116
+ ```
117
+
118
+ ---
119
+
120
+ ## Updating
121
+
122
+ - **MCP server**: nothing to do. The toolkit runs `npx -y @kelviq/mcp-server@latest`, which checks for the newest published version each time the server starts.
123
+ - **Skills** (Claude Code): `/plugin marketplace update kelviq` pulls the latest marketplace content.
124
+ - **Skills** (other agents): re-run `npx skills add kelviq/agent-toolkit`.
125
+
126
+ ---
127
+
128
+ ## Troubleshooting
129
+
130
+ **`kelviq:` tools aren't available** — on Claude Code, check `/mcp`; if the server isn't listed, reinstall the plugin. On other agents, the skills-only install doesn't include the server — follow the Setup section in any installed skill or the [MCP server guide](/guides/mcp-server).
131
+
132
+ **`Configuration error` from API tools** — `KELVIQ_SERVER_API_KEY` isn't visible to the process that launched your agent. Set it in your shell profile (not just the current terminal) and restart the agent.
133
+
134
+ **"Not found" on an identifier you can see in the dashboard** — your key and `KELVIQ_ENV` are probably pointing at the other environment. Sandbox and production are fully separate; a key only works against its own environment.
135
+
136
+ ---
137
+
138
+ ## Related
139
+
140
+ - [MCP server guide](/guides/mcp-server) — manual per-client setup, full tool list, architecture
141
+ - [Kelviq CLI](/cli/overview) — the pricing-as-code workflow the `pricing-as-code` skill teaches
142
+ - [Sandbox](/guides/sandbox) — test environment setup
143
+ - [github.com/kelviq/agent-toolkit](https://github.com/kelviq/agent-toolkit) — the toolkit source