@kelviq/mcp-server 1.2.0 → 1.3.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 (111) hide show
  1. package/README.md +40 -3
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +1 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/ai/docs-for-agents.md +21 -0
  6. package/dist/docs/ai/overview.md +43 -0
  7. package/dist/docs/api-reference/authentication.md +9 -3
  8. package/dist/docs/api-reference/introduction.md +23 -2
  9. package/dist/docs/backend-integration/node-sdk.md +12 -6
  10. package/dist/docs/backend-integration/python-sdk.md +14 -8
  11. package/dist/docs/changelog.md +369 -3
  12. package/dist/docs/checkout/checkout-configuration.md +25 -75
  13. package/dist/docs/checkout/checkout-design.md +76 -0
  14. package/dist/docs/checkout/checkout-examples.md +212 -0
  15. package/dist/docs/checkout/checkout-metadata.md +1 -1
  16. package/dist/docs/checkout/custom-fields.md +60 -0
  17. package/dist/docs/checkout/embed-checkout.md +280 -0
  18. package/dist/docs/checkout/payment-methods/upi.md +69 -0
  19. package/dist/docs/checkout/payment-methods.md +119 -0
  20. package/dist/docs/checkout/static-checkout-url.md +3 -2
  21. package/dist/docs/cli/commands.md +57 -4
  22. package/dist/docs/cli/kelviq-config.md +1 -1
  23. package/dist/docs/cli/overview.md +1 -0
  24. package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
  25. package/dist/docs/customer-portal/overview.md +7 -7
  26. package/dist/docs/customer-portal/retention.md +109 -0
  27. package/dist/docs/customers-management/overview.md +105 -0
  28. package/dist/docs/frontend-integration/js-sdk.md +11 -11
  29. package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
  30. package/dist/docs/frontend-integration/react-sdk.md +8 -49
  31. package/dist/docs/frontend-integration/react-ui.md +8 -6
  32. package/dist/docs/getstarted/fees.md +27 -11
  33. package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
  34. package/dist/docs/getstarted/merchant-of-record.md +18 -24
  35. package/dist/docs/getstarted/overview.md +98 -0
  36. package/dist/docs/getstarted/review-process.md +59 -59
  37. package/dist/docs/guides/agent-toolkit.md +14 -9
  38. package/dist/docs/guides/mcp-server.md +24 -9
  39. package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
  40. package/dist/docs/guides/sandbox.md +6 -4
  41. package/dist/docs/guides/set-up-with-ai.md +43 -0
  42. package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
  43. package/dist/docs/guides/subscription-integration.md +1 -1
  44. package/dist/docs/guides/test-payments.md +640 -0
  45. package/dist/docs/guides/webhooks.md +182 -30
  46. package/dist/docs/integrations/woocommerce.md +88 -0
  47. package/dist/docs/integrations/zapier.md +22 -0
  48. package/dist/docs/legal/account-and-funds.md +59 -0
  49. package/dist/docs/legal/approved-prohibited-policy.md +32 -27
  50. package/dist/docs/legal/payment-flow-diagram.md +7 -7
  51. package/dist/docs/manifest.json +160 -41
  52. package/dist/docs/openapi.json +1359 -109
  53. package/dist/docs/payouts/overview.md +14 -12
  54. package/dist/docs/payouts/payout-account.md +1 -1
  55. package/dist/docs/payouts/transactions.md +3 -3
  56. package/dist/docs/product-catalog/create-a-feature.md +3 -3
  57. package/dist/docs/product-catalog/digital-downloads.md +5 -5
  58. package/dist/docs/product-catalog/discounts.md +2 -2
  59. package/dist/docs/product-catalog/entitlements.md +20 -27
  60. package/dist/docs/product-catalog/free-and-trials.md +5 -5
  61. package/dist/docs/product-catalog/license-keys.md +56 -29
  62. package/dist/docs/product-catalog/links.md +3 -3
  63. package/dist/docs/product-catalog/location-based-pricing.md +6 -10
  64. package/dist/docs/product-catalog/one-time-payments.md +3 -7
  65. package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
  66. package/dist/docs/product-catalog/plans.md +22 -19
  67. package/dist/docs/product-catalog/products.md +11 -3
  68. package/dist/docs/product-catalog/proration.md +69 -0
  69. package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
  70. package/dist/docs/product-catalog/subscriptions.md +52 -22
  71. package/dist/docs/product-catalog/tax-settings.md +8 -8
  72. package/dist/docs/product-catalog/usage-alerts.md +7 -7
  73. package/dist/docs/product-catalog/usage-based-billing.md +156 -29
  74. package/dist/docs/product-catalog/usage-limits.md +78 -0
  75. package/dist/docs/promotions/create-a-promotion.md +2 -2
  76. package/dist/docs/promotions/overview.md +1 -1
  77. package/dist/docs/quickstart/core-concepts.md +36 -30
  78. package/dist/docs/quickstart/dashboard-setup.md +26 -22
  79. package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
  80. package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
  81. package/dist/docs/sales/checkout-sessions.md +28 -39
  82. package/dist/docs/sales/orders.md +30 -54
  83. package/dist/docs/settings/customer-emails.md +52 -0
  84. package/dist/docs/settings/members.md +27 -0
  85. package/dist/docs/settings/profile.md +26 -0
  86. package/dist/docs/settings/zapier.md +22 -0
  87. package/dist/http/errors.d.ts +20 -1
  88. package/dist/http/errors.js +83 -31
  89. package/dist/http/errors.js.map +1 -1
  90. package/dist/schemas/kelviq.d.ts +54 -0
  91. package/dist/schemas/kelviq.js +64 -0
  92. package/dist/schemas/kelviq.js.map +1 -1
  93. package/dist/server.js +3 -2
  94. package/dist/server.js.map +1 -1
  95. package/dist/tools/_resolve.js +14 -10
  96. package/dist/tools/_resolve.js.map +1 -1
  97. package/dist/tools/features.js +9 -2
  98. package/dist/tools/features.js.map +1 -1
  99. package/dist/tools/imports.d.ts +68 -0
  100. package/dist/tools/imports.js +242 -0
  101. package/dist/tools/imports.js.map +1 -0
  102. package/dist/tools/index.d.ts +2 -1
  103. package/dist/tools/index.js +4 -1
  104. package/dist/tools/index.js.map +1 -1
  105. package/dist/tools/product-files.js +10 -3
  106. package/dist/tools/product-files.js.map +1 -1
  107. package/dist/tools/product-settings.js +10 -3
  108. package/dist/tools/product-settings.js.map +1 -1
  109. package/dist/tools/products.js +14 -4
  110. package/dist/tools/products.js.map +1 -1
  111. package/package.json +1 -1
@@ -17,7 +17,7 @@ Use Links to share:
17
17
 
18
18
  ## Accessing Links
19
19
 
20
- <img height="200" src="/images/accessing-links.png" />
20
+ <img src="/images/accessing-links.webp" />
21
21
 
22
22
  1. Navigate to **Products** in the sidebar
23
23
  2. Select the product containing your plan
@@ -31,7 +31,7 @@ The section header shows the current count of saved links (e.g., "Links (3)").
31
31
 
32
32
  ### How to Add a Link
33
33
 
34
- <img height="200" src="/images/adding-links.png" />
34
+ <img src="/images/adding-links.webp" />
35
35
 
36
36
  1. Open the **Links** section
37
37
  2. You'll see two input fields:
@@ -69,7 +69,7 @@ Choose clear, descriptive names that tell customers what they'll access:
69
69
 
70
70
  ### Remove a Link
71
71
 
72
- <img height="200" src="/images/remove-links.png" />
72
+ <img src="/images/remove-links.webp" />
73
73
 
74
74
  1. Open the **Links** section
75
75
  2. Click the **×** button next to the link you want to remove
@@ -10,34 +10,30 @@ Location based pricing is a feature that allows you to set custom prices for spe
10
10
 
11
11
  To offer a localized price open your plan configuration and expand the Price localization card.
12
12
 
13
- Regional prices inherit the base price's usage reset, usage alert, and credit rollover settings. Regional pricing changes the localized monetary price; it does not create a separate usage-policy configuration.
13
+ Localized prices inherit the base price's usage reset, usage alert, and credit rollover settings. Price localization changes the localized monetary price; it does not create a separate usage-policy configuration.
14
14
 
15
15
  ### 1. Choose a currency
16
16
 
17
17
  Select your target currency from the dropdown list. You can choose options like Euro or Indian Rupee. Click Add localized price to open the configuration panel.
18
18
 
19
- <img height="200" src="/images/choose-currency.png" />
19
+ <img src="/images/choose-currency.webp" />
20
20
 
21
21
  ### 2. Set the fixed base charge
22
22
 
23
23
  Kelviq automatically displays the billing cycles you already enabled for your default base price and usage based pricing. Enter the exact localized amount you want to charge for each active interval.
24
24
 
25
- <img height="400" src="/images/base-pricing.png" />
25
+ <img src="/images/base-pricing.webp" />
26
26
 
27
27
  ### 3. Localize usage based features
28
28
 
29
- If your plan includes metered features like API calls Kelviq pulls those in automatically right below the fixed charge section. You can set localized unit prices and flat fees for every single usage tier.
29
+ If your plan includes Meter features like API calls Kelviq pulls those in automatically right below the fixed charge section. You can set localized unit prices and flat fees for every single usage tier.
30
30
 
31
31
  You must configure these usage rates across all active billing periods. Use the tabs to switch between your monthly and yearly configurations and ensure every input has a defined price.
32
32
 
33
- <img height="600" src="/images/usage-pricing.png" />
33
+ <img src="/images/usage-pricing.webp" />
34
34
 
35
35
  ### 4. Save and stack regions
36
36
 
37
37
  Click Save to lock in the location based pricing configuration. The currency will appear in your localized pricing list.
38
38
 
39
- You can repeat this process to add as many localized currencies as you need.
40
-
41
- ## Fraud protection
42
-
43
- Kelviq analyzes the IP address, browser fingerprint, and issuing bank of the credit card during checkout. If a customer attempts to use a card from a high income country while pretending to be in a lower income region we block the transaction or force the standard global price automatically.
39
+ You can repeat this process to add as many localized currencies as you need.
@@ -8,14 +8,14 @@ Not every product needs a subscription. If you are selling a lifetime software l
8
8
 
9
9
  ## Set up a one time price
10
10
 
11
- <img height="200" src="/images/One-time.png" />
11
+ <img src="/images/One-time.webp" />
12
12
 
13
13
  1. Open your draft plan and ensure it is set to Paid
14
14
  2. Under the billing cycles select One time
15
15
  3. Enter the total amount you want to charge
16
16
  4. Click Save
17
17
 
18
- One-time payments do not support free trials. To offer a trial, add and enable a recurring billing cycle on the plan.
18
+ Free trials work on recurring billing cycles. To offer one, add and enable a recurring billing cycle on the plan.
19
19
 
20
20
  Customers pay this amount exactly once during checkout. If you attach digital downloads or license keys to this plan they gain permanent access to those assets immediately after payment.
21
21
 
@@ -23,8 +23,4 @@ If an existing customer already has a saved payment method, you can also [create
23
23
 
24
24
  ## Combine with usage
25
25
 
26
- You can charge a one time setup fee and still bill for ongoing usage.
27
-
28
- Just select One time for the base fee and add your metered features below it. The customer pays the base price upfront to gain access and then pays for their compute or token usage at the end of each billing period.
29
-
30
- Please note that when combining a one-time base fee with metered features, the usage-based pricing models are limited to **flat** and **package** pricing options.
26
+ To charge a fixed fee plus usage, use a **Monthly** price with a Pay as you go usage charge. Pay as you go bills monthly, so it pairs with Monthly prices. See [Pay as you go](/product-catalog/pay-as-you-go).
@@ -8,7 +8,7 @@ With pay as you go, the customer does not buy a block of usage upfront. Your bac
8
8
 
9
9
  The same plan can contain a monthly base price and one or more usage charges. You define the billable feature and its rates in the dashboard; your application supplies the usage.
10
10
 
11
- Monthly must be the plan's only billing period. Pay as you go cannot be used on a plan that also offers yearly, quarterly, one-time, or another billing period.
11
+ Pay as you go plans bill monthly, so Monthly is the plan's only billing period.
12
12
 
13
13
  ## Before you start
14
14
 
@@ -25,10 +25,10 @@ Pay as you go supports **Flat**, **Package**, **Tiered**, and **Volume** pricing
25
25
 
26
26
  1. Open the product and edit its plan.
27
27
  2. In the plan's billing periods, keep **Monthly** enabled and turn off every other period.
28
- 3. Open **Usage charges** and select the metered feature you want to bill for. If the list is empty, [create a Meter feature](/product-catalog/create-a-feature) from **Product catalog → Features** first.
28
+ 3. Open **Usage charges** and select the Meter feature you want to bill for. If the list is empty, [create a Meter feature](/product-catalog/create-a-feature) from **Product catalog → Features** first.
29
29
  4. For **Billing model**, choose **Pay-as-you-go**.
30
30
 
31
- <img src="/images/select-billing-model.png" alt="Selecting Pay-as-you-go as the billing model in Kelviq" />
31
+ <img src="/images/select-billing-model-payg.webp" alt="Selecting Pay-as-you-go as the billing model in Kelviq" />
32
32
 
33
33
  5. Choose a pricing model and enter its rates.
34
34
  6. Add [usage alerts](/product-catalog/usage-alerts) if you want to notify your application when usage crosses a threshold.
@@ -45,9 +45,9 @@ The billing model controls *when* the customer pays. The pricing model controls
45
45
  | Flat | Uses one rate for every unit | $0.001 per API call |
46
46
  | Package | Bills in blocks of units | $2 per 10,000 tokens |
47
47
  | Tiered | Applies each rate only to the units inside that tier | First 100,000 tokens free, then $0.0002 per token |
48
- | Volume | Uses the rate for the customer's final usage band across all units | $0.01 per request, or $0.007 for all requests after 100,000 |
48
+ | Volume | Uses the rate for the customer's final usage band across all units | \$0.01 per request, or \$0.007 for all requests after 100,000 |
49
49
 
50
- See [Usage based pricing](/product-catalog/usage-based-billing) for the full calculation rules and examples for each model.
50
+ See [Usage-based pricing](/product-catalog/usage-based-billing) for the full calculation rules and examples for each model.
51
51
 
52
52
  ### Combine a base price with usage
53
53
 
@@ -59,11 +59,11 @@ Included usage: 100,000 tokens
59
59
  Additional usage: $0.0002 per token
60
60
  ```
61
61
 
62
- If the customer uses 120,000 tokens, the first 100,000 fall into a zero-priced tier. The remaining 20,000 tokens cost $4, so the period total is $24 before tax.
62
+ If the customer uses 120,000 tokens, the first 100,000 fall into a zero-priced tier. The remaining 20,000 tokens cost \$4, so the period total is \$24 before tax.
63
63
 
64
64
  ## Report usage from your backend
65
65
 
66
- Kelviq can only bill usage that your application reports. Send usage from trusted server-side code after the billable action succeeds. Do not expose a server API key in browser or mobile code.
66
+ Kelviq bills the usage your application reports. Send it from trusted server-side code after the billable action succeeds. Do not expose a server API key in browser or mobile code.
67
67
 
68
68
  ### Node.js
69
69
 
@@ -98,7 +98,7 @@ await client.reporting.reportUsage({
98
98
  | Field | What to send |
99
99
  | --- | --- |
100
100
  | `customerId` | The same customer identifier used for the subscription |
101
- | `featureId` | The identifier of the metered feature on the plan |
101
+ | `featureId` | The identifier of the Meter feature on the plan |
102
102
  | `value` | A whole-number usage quantity |
103
103
  | `behaviour` | `DELTA` to add usage or `SET` to replace the current value |
104
104
 
@@ -63,7 +63,7 @@ You create plans directly inside a product container.
63
63
  Navigate to the **Product detail page** and click **+ Create plan**.
64
64
 
65
65
 
66
- <img height="200" src="/images/create-plan.png" />
66
+ <img src="/images/create-plan.webp" />
67
67
 
68
68
 
69
69
 
@@ -76,7 +76,7 @@ You create plans directly inside a product container.
76
76
  * **Description:** Optional text shown on invoices and checkout.
77
77
 
78
78
 
79
- <img height="200" src="/images/create-plan-modal.png" />
79
+ <img src="/images/create-plan-modal.webp" />
80
80
 
81
81
 
82
82
 
@@ -105,16 +105,16 @@ Once your plan draft exists you can configure how you charge. We split these int
105
105
  * [Subscriptions](/product-catalog/subscriptions)
106
106
  * [Enterprise and bespoke plans](/product-catalog/create-an-enterprise-plan)
107
107
  * [Seat based pricing](/product-catalog/seat-based-pricing)
108
- * [Usage based pricing](/product-catalog/usage-based-billing)
108
+ * [Usage-based pricing](/product-catalog/usage-based-billing)
109
109
  * [Free plans and trials](/product-catalog/free-and-trials)
110
110
  * [Location based pricing](/product-catalog/location-based-pricing)
111
111
 
112
- <img height="200" src="/images/configure-price.png" />
112
+ <img src="/images/configure-price.webp" />
113
113
 
114
114
  ### Free vs. Paid
115
115
  Use the toggle in the top right to switch between a free or paid plan.
116
116
 
117
- <img height="200" src="/images/free-paid.png" />
117
+ <img src="/images/free-paid.webp" />
118
118
 
119
119
  * **Free plan:** Users are not charged. Useful for lead magnets or open-source tiers.
120
120
  * **Paid plan:** Unlocks the billing configuration options below.
@@ -122,9 +122,9 @@ Use the toggle in the top right to switch between a free or paid plan.
122
122
  ### Billing cycles
123
123
  Select the intervals you want to offer. You can enable multiple intervals for a single plan.
124
124
 
125
- <img height="200" src="/images/billing-cycle.png" />
125
+ <img src="/images/billing-cycle.webp" />
126
126
 
127
- * **28 days:** A recurring four-week subscription.
127
+ * **28 days:** A recurring four-week subscription. Shown once we enable it for your organization.
128
128
  * **Monthly / Yearly:** Standard recurring subscriptions.
129
129
  * **3 Months:** Quarterly billing.
130
130
  * **6 Months:** Billing twice a year.
@@ -132,13 +132,14 @@ Select the intervals you want to offer. You can enable multiple intervals for a
132
132
 
133
133
  The 28-day period is useful when you need a consistent four-week renewal schedule rather than a calendar-month renewal.
134
134
 
135
- To test a renewal without waiting for a full month, use a daily billing interval in Sandbox mode. See [Test a subscription renewal](/guides/sandbox#test-a-subscription-renewal).
135
+ To test a renewal without waiting a full month, ask support to enable daily billing for your sandbox. See [Test a subscription renewal](/guides/sandbox#test-a-subscription-renewal).
136
136
 
137
137
  ### Location based pricing
138
138
  You can set specific prices for different countries rather than relying on auto-conversion.
139
- 1. Click **+ Add localized price**.
140
- 2. Select the currency (e.g. EUR, INR).
141
- 3. Enter the price for that market.
139
+ 1. In the price editor, expand **Price localization**.
140
+ 2. Under **Choose a currency**, select a currency (e.g. EUR, INR) and click **Add localized price**.
141
+ 3. Enter the price for each billing cycle, then click **Save** in that currency's panel.
142
+ 4. Click **Save** at the bottom of the price editor.
142
143
 
143
144
  ---
144
145
 
@@ -156,9 +157,10 @@ Upload files that are securely delivered after purchase.
156
157
  If you are selling software that requires activation, you can issue unique license keys.
157
158
  1. Expand the **License keys** accordion.
158
159
  2. **Activation limit:** Set how many machines or instances can use a single key (e.g. 1 for personal, 5 for team).
159
- 3. **License duration:** Define how long the key remains valid (e.g. 1 Year).
160
+ 3. **License expiry:** Define how long the key remains valid (e.g. 1 Year).
161
+ 4. Click **Save Changes**. On a published plan, this creates an unpublished version, so publish the update when you're ready.
160
162
 
161
- ### External links
163
+ ### Links
162
164
  Provide access to resources hosted elsewhere.
163
165
  1. Expand the **Links** accordion.
164
166
  2. Add the **Link name** (e.g. Private Discord community).
@@ -166,7 +168,7 @@ Provide access to resources hosted elsewhere.
166
168
 
167
169
  ---
168
170
 
169
- ## Feature & limits
171
+ ## Features & limits
170
172
  Configure feature access, usage quotas, and API limits.
171
173
 
172
174
  * **Toggle features:** Turn specific capabilities on or off (e.g. "SSO Access").
@@ -201,13 +203,14 @@ If you change your mind while editing, you can click **Discard** to delete the u
201
203
 
202
204
  ### Plan actions
203
205
 
204
- Click the **⋯** menu next to the **Publish updates** button to access additional options.
206
+ Click the **⋯** menu next to the **Publish** button (**Publish updates** on a plan with unpublished changes) to see more options.
205
207
 
206
208
  | Action | Description |
207
209
  |--------|-------------|
208
210
  | **Edit** | Open the plan configuration to make changes |
209
211
  | **Get Link** | Copy the direct checkout link for this plan |
210
- | **Restrict by country** | Limit which countries can purchase this plan |
211
- | **Archive** | Hide the plan from new customers while keeping it active for existing subscribers |
212
- | **Restore last published version** | Discard unpublished changes and revert to the live version |
213
- | **See last published version** | Preview what customers currently see on the live plan |
212
+ | **Country restrictions** | Limit which countries can purchase this plan |
213
+ | **Tax behavior** | Choose whether prices include tax or tax is added at checkout |
214
+ | **Delete** | Remove the plan |
215
+ | **Restore last published version** | Shown on a plan with unpublished changes. Discard unpublished changes and revert to the live version |
216
+ | **View published version** | Shown on a plan with unpublished changes. Preview what customers currently see on the live plan |
@@ -8,7 +8,7 @@ A product is the top-level container for what you sell. It groups together your
8
8
 
9
9
  Before you can create plans or configure billing logic, you need to define the product they belong to.
10
10
 
11
- <img height="200" src="/images/product-empty-screen.png" />
11
+ <img src="/images/product-empty-screen.webp" />
12
12
 
13
13
  ## Create a product
14
14
 
@@ -24,7 +24,7 @@ Follow these steps to set up a new product.
24
24
  Click **+ Create product** in the top right corner.
25
25
 
26
26
 
27
- <img height="200" src="/images/create-new-product.png" />
27
+ <img src="/images/create-new-product.webp" />
28
28
 
29
29
 
30
30
 
@@ -45,7 +45,15 @@ Follow these steps to set up a new product.
45
45
  Click **Create**. You will be redirected to the product details page.
46
46
 
47
47
 
48
- <img height="200" src="/images/product-created.png" />
48
+ <img src="/images/product-created.webp" />
49
+
50
+ ## Default currency
51
+
52
+ Each product has a default currency. Checkout shows that currency first, so set it to the currency most of your buyers pay in.
53
+
54
+ To change it, open the product's **⋯** menu and choose **Settings**.
55
+
56
+ After you change the default currency, add a price in that currency to every plan in the product. A plan without one only appears in countries where it has a [localized price](/product-catalog/location-based-pricing).
49
57
 
50
58
  ## Next steps
51
59
 
@@ -0,0 +1,69 @@
1
+ ---
2
+ title: "Proration"
3
+ slug: "product-catalog/proration"
4
+ section: "product-catalog"
5
+ description: "What a customer pays when they change plans in the middle of a billing period"
6
+ ---
7
+ When a customer changes plans mid-period, proration decides what they pay for the time left. Kelviq credits the unused part of the old plan and charges for the rest of the period on the new plan. You choose whether that difference is charged now, added to the next invoice, or skipped.
8
+
9
+ Both examples below use monthly plans, with the change made exactly halfway through the month.
10
+
11
+ ## Upgrade: \$100 → \$200
12
+
13
+ The unused half of the old plan is worth a \$50 credit. The remaining half of the new plan costs \$100. The difference is \$50.
14
+
15
+ | Option | Today | Next renewal |
16
+ | --- | --- | --- |
17
+ | **Immediate charge** | \$50 charged | \$200 |
18
+ | **Prorate on next invoice** | Nothing | \$200 + \$50 = \$250 |
19
+ | **No proration** | Nothing | \$200 |
20
+
21
+ ## Downgrade: \$200 → \$100
22
+
23
+ The unused half of the old plan is worth a \$100 credit. The remaining half of the new plan costs \$50. The customer is owed \$50.
24
+
25
+ | Option | Today | Next renewal |
26
+ | --- | --- | --- |
27
+ | **Immediate charge** | Nothing; \$50 is kept as account credit | \$100, less the \$50 credit = \$50 |
28
+ | **Prorate on next invoice** | Nothing | \$100 − \$50 = \$50 |
29
+ | **No proration** | Nothing | \$100 |
30
+
31
+ The new plan and its limits apply as soon as the change is made, whichever option you pick. Amounts depend on the exact time of the change.
32
+
33
+ ## Set your defaults
34
+
35
+ Open **Settings → Subscription proration**. There are two defaults:
36
+
37
+ | Setting | Applies to | Default |
38
+ | --- | --- | --- |
39
+ | **Plan upgrades & downgrades** | A customer moving to a different plan | Immediate charge |
40
+ | **Plan version migrations** | Moving customers to a new version of the same plan | Prorate on next invoice |
41
+
42
+ <img src="/images/subscription-proration-settings.webp" alt="The Subscription proration settings page with defaults for plan changes and plan version migrations" />
43
+
44
+ Switching between monthly and yearly billing always invoices immediately, whatever you choose here. The change starts a new billing period and sets the new renewal date. With **No proration**, unused time on the old interval isn't credited.
45
+
46
+ ## Override per change
47
+
48
+ Pass `prorationBehavior` when you update a subscription through the API or SDK. It overrides the default for that change.
49
+
50
+ | Value | Dashboard name |
51
+ | --- | --- |
52
+ | `IMMEDIATE_CHARGE` | Immediate charge |
53
+ | `PRORATE_NEXT_INVOICE` | Prorate on next invoice |
54
+ | `NO_PRORATION` | No proration |
55
+
56
+ ```ts
57
+ import { CHARGE_PERIOD_CHOICES, PRORATION_BEHAVIORS } from '@kelviq/node-sdk';
58
+
59
+ await client.subscriptions.update({
60
+ subscriptionId: 'sub_123',
61
+ planIdentifier: 'pro',
62
+ chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
63
+ prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
64
+ });
65
+ ```
66
+
67
+ To see the exact amounts before you commit, call `client.subscriptions.previewUpdate` with the same fields, or `POST /subscriptions/{subscriptionId}/update/preview/`.
68
+
69
+ To keep the old plan until the customer pays for the new one, see [Wait for payment before changing access](/product-catalog/subscriptions#wait-for-payment-before-changing-access).
@@ -47,7 +47,7 @@ Use a Meter feature rather than a Customizable feature. Kelviq can attach a pric
47
47
  3. Enter the plan's base price. Use this for the fixed part of the subscription, if any.
48
48
  4. Open **Usage charges**.
49
49
 
50
- <img src="/images/usage-pricing-card.png" alt="Usage charges section for API requests or seats in Kelviq" />
50
+ <img src="/images/usage-pricing-card.webp" alt="Usage charges section for API requests or seats in Kelviq" />
51
51
 
52
52
  5. Select the `seats` feature.
53
53
  6. For **Billing model**, choose **Advance commitment**. The customer is purchasing the seats before using them.
@@ -55,7 +55,7 @@ Use a Meter feature rather than a Customizable feature. Kelviq can attach a pric
55
55
  8. Enter the price per unit for every billing period. For example, use `$12` under Monthly and `$120` under Yearly.
56
56
  9. Save the price and publish the plan.
57
57
 
58
- <img src="/images/select-billing-model.png" alt="Advance commitment and Pay-as-you-go billing model options in Kelviq" />
58
+ <img src="/images/select-billing-model-advance.webp" alt="Advance commitment and Pay-as-you-go billing model options in Kelviq" />
59
59
 
60
60
  The seat rate belongs under Usage charges even though this is not usage billed in arrears. **Advance commitment** is what makes the selected quantity an upfront seat purchase.
61
61
 
@@ -65,13 +65,13 @@ Most teams start with one price per seat. You can also sell seats in packages, l
65
65
 
66
66
  | Pricing model | Seat calculation | Example |
67
67
  | --- | --- | --- |
68
- | Flat | Every seat has the same price | 8 seats × $12 = $96 |
68
+ | Flat | Every seat has the same price | 8 seats × \$12 = \$96 |
69
69
  | Package | Seats are sold in fixed-size packs | $50 for each block of 5 seats |
70
- | Tiered | Each range of seats uses its own rate | Seats 1–10 at $15, then seats 11–25 at $12 |
71
- | Volume | The final seat count sets the rate for every seat | 1–10 seats at $15 each; 11+ seats at $12 each |
72
- | Stair-step | The seat count selects one fixed charge | $100 for up to 10 seats; $220 for up to 25 |
70
+ | Tiered | Each range of seats uses its own rate | Seats 1–10 at \$15, then seats 11–25 at \$12 |
71
+ | Volume | The final seat count sets the rate for every seat | 1–10 seats at \$15 each; 11+ seats at \$12 each |
72
+ | Stair-step | The seat count selects one fixed charge | \$100 for up to 10 seats; \$220 for up to 25 |
73
73
 
74
- See [Usage based pricing](/product-catalog/usage-based-billing) for the calculation rules for Package, Tiered, Volume, and Stair-step pricing.
74
+ See [Usage-based pricing](/product-catalog/usage-based-billing) for the calculation rules for Package, Tiered, Volume, and Stair-step pricing.
75
75
 
76
76
  ## Send the seat count to checkout
77
77
 
@@ -8,7 +8,7 @@ Subscriptions are the default for traditional SaaS products. You charge customer
8
8
 
9
9
  ## Set up recurring billing
10
10
 
11
- <img height="200" src="/images/subscription-pricing.png" />
11
+ <img src="/images/subscription-pricing.webp" />
12
12
 
13
13
  1. Open a draft plan and make sure it is set to **Paid**.
14
14
  2. Under **Billing cycles**, select the recurring intervals you want to offer, such as **28 days**, **Monthly**, **3 Months**, **6 Months**, or **Yearly**.
@@ -48,19 +48,9 @@ Omit `paymentBehavior` to keep the default immediate-update behavior.
48
48
 
49
49
  ### Control how a change is billed
50
50
 
51
- Pass `prorationBehavior` when you update a subscription to choose when the customer pays for a mid-period change:
51
+ Proration decides what the customer pays for the rest of the period: charged now (`IMMEDIATE_CHARGE`), added to the next invoice (`PRORATE_NEXT_INVOICE`), or skipped (`NO_PRORATION`). Set your defaults in **Settings → Subscription proration**, or pass `prorationBehavior` when you update a subscription.
52
52
 
53
- | Value | Effect |
54
- | --- | --- |
55
- | `IMMEDIATE_CHARGE` | Applies the change now, prorates the difference, and invoices it immediately. |
56
- | `PRORATE_NEXT_INVOICE` | Applies the change now and adds the prorated credit or charge to the next renewal invoice. Nothing is collected immediately. |
57
- | `NO_PRORATION` | Applies the change now without crediting or charging for the partial period. The next renewal invoice bills the full new price. |
58
-
59
- If you omit the field, Kelviq uses your organization's default. Set the defaults with `PATCH /organizations/settings/`: `updateSubscriptionProrationBehavior` covers upgrades and downgrades and defaults to `IMMEDIATE_CHARGE`, while `migrateSubscriptionProrationBehavior` covers plan migrations and defaults to `PRORATE_NEXT_INVOICE`.
60
-
61
- Changing the billing interval, such as monthly to yearly, starts and invoices the new billing period immediately, whichever option you pass. With `NO_PRORATION`, unused time on the old interval is not credited. The update time becomes the start of the new billing period and sets the new renewal date.
62
-
63
- To see the exact amounts before committing to a change, call `POST /subscriptions/{subscriptionId}/update/preview/` with the same payload. If credits exceed the new charge, no payment is collected and the remainder is kept as customer credit.
53
+ [Proration](/product-catalog/proration) walks through each option with an upgrade and a downgrade example. The defaults are also available through the API as `updateSubscriptionProrationBehavior` and `migrateSubscriptionProrationBehavior` on `PATCH /organizations/settings/`.
64
54
 
65
55
  ### Wait for payment before changing access
66
56
 
@@ -75,7 +65,7 @@ To see the exact amounts before committing to a change, call `POST /subscription
75
65
 
76
66
  Card payments that do not require authentication are usually completed during the update request, so the status change can happen immediately. When the payment method requires customer action, continue using the existing subscription until the updated subscription becomes `active`.
77
67
 
78
- A successful update API response does not always mean the new plan is active. When you use `activate_on_payment`, check the subscription status or the customer's current entitlements before granting access to the new plan.
68
+ With `activate_on_payment`, the new plan goes live after its payment succeeds. Check the subscription's plan or the customer's entitlements before granting access to the new plan.
79
69
 
80
70
  ### Upgrades
81
71
 
@@ -83,13 +73,13 @@ Under the default `IMMEDIATE_CHARGE` proration behavior, Kelviq prorates the pri
83
73
 
84
74
  With `activate_on_payment`, Kelviq waits for that payment to succeed before activating the upgraded plan.
85
75
 
86
- For example, if a customer moves from a \$100 monthly plan to a $200 monthly plan halfway through the period, the approximate calculation is:
76
+ For example, if a customer moves from a \$100 monthly plan to a \$200 monthly plan halfway through the period, the approximate calculation is:
87
77
 
88
78
  | Item | Amount |
89
79
  | --- | ---: |
90
- | Unused half of the old plan | -$50 credit |
91
- | Remaining half of the new plan | $100 charge |
92
- | Net amount collected | $50 |
80
+ | Unused half of the old plan | -\$50 credit |
81
+ | Remaining half of the new plan | \$100 charge |
82
+ | Net amount collected | \$50 |
93
83
 
94
84
  The exact amount depends on when the upgrade is processed. Existing usage counters are retained and evaluated against the new plan's limits.
95
85
 
@@ -103,15 +93,55 @@ Under the default payment behavior, downgrades also apply immediately. If the cu
103
93
 
104
94
  When cancelling, choose whether the subscription should end immediately or at the end of the current billing period. A plan downgrade and a subscription cancellation are separate actions: the downgrade follows the payment behavior you choose, while the cancellation follows the timing option you select.
105
95
 
96
+ ## Pause a subscription
97
+
98
+ A paused subscription stops billing and stops access. The customer isn't charged, their entitlements return `hasAccess: false`, and plan changes are blocked until the subscription resumes. Cancelling stays available.
99
+
100
+ When a customer tries to cancel, Kelviq shows the offer you've set for the reason they give: a discount, a pause, or a link to your support team. If the offer is a pause and they accept it, they pick a length from the ones you allow: 1, 3, or 6 months. This works in the customer portal and from a Cancel button in your own app. See [Retention offers](/customer-portal/retention#where-customers-see-offers).
101
+
102
+ A pause has to cover at least one full billing period, so yearly plans can't be paused. Only an `active` subscription can be paused, not one on trial, past due, already paused, or scheduled to cancel. Free and manually billed subscriptions can't be paused.
103
+
104
+ ### Resume a subscription
105
+
106
+ A paused subscription resumes on its own at the end of the pause. Choose what happens on resume in **Settings → Retention → Advanced settings**:
107
+
108
+ | | Reset billing cycle (default) | Keep billing day |
109
+ | --- | --- | --- |
110
+ | Charged on resume | A full period | Nothing |
111
+ | Next charge | One period after the resume date | The original billing day |
112
+ | Billing day afterwards | The resume date | Unchanged |
113
+
114
+ For a monthly plan billed on the 1st, paused on 10 September and resumed on 20 October, reset charges a full month on 20 October and bills on the 20th from then on. Keep billing day charges nothing and bills on 1 November as before, which gives the customer free access from the 20th to the 1st. A customer who resumes inside a period they've already paid for is never charged again, whichever behavior you pick.
115
+
116
+ On resume, entitlements come back with usage reset to zero and a fresh period.
117
+
118
+ ### What changes while paused
119
+
120
+ The subscription has `status: "paused"`, `pausedAt`, and `pauseResumesAt` (`null` for an open-ended pause). Kelviq sends `subscription.paused` and `subscription.resumed` [webhooks](/guides/webhooks), whichever surface the change came from. Webhook payloads use snake_case, so the same fields arrive there as `paused_at` and `pause_resumes_at`. Renewals that would fall inside the pause are skipped silently, so a paused subscription sends no other events until it resumes.
121
+
122
+ If you cache entitlement checks, clear them when you receive `subscription.paused`, otherwise the customer keeps access until the cache expires. Both SDKs have a call for it: `client.entitlements.invalidateCache({ customerId })` in Node and `client.entitlements.invalidate_cache(customerId=...)` in Python.
123
+
124
+ ### Retention offers
125
+
126
+ Before a customer cancels, you can offer them a reason to stay. In the dashboard retention settings, switch retention on and map each cancellation reason to an offer:
127
+
128
+ * **Discount**: a percentage off for a set number of billing cycles, applied as a single-use coupon.
129
+ * **Pause**: a break of one of the lengths you allow. Billing and access stop, then resume on a renewal boundary.
130
+ * **Support**: a link to a booking page or support form, for reasons a conversation can fix.
131
+
132
+ The customer portal shows these offers automatically. To build the same flow in your own app, call [Get retention offers](/api-reference/subscriptions/get-retention-offers) for the subscription. It returns every cancellation reason with its configured offer and whether this subscription is eligible for it right now, so you can show an unavailable offer greyed out with a reason. When the customer takes an offer, call [Accept a retention offer](/api-reference/subscriptions/accept-a-retention-offer) with the reason and the offer. If they cancel anyway, call [Cancel a subscription](/api-reference/subscriptions/cancel-a-subscription) with the same reason as `cancellationFeedback`.
133
+
134
+ An offer must be the one configured for the reason the customer picked, and eligibility is checked again when it is accepted. The repeat policy you set decides whether a customer who has already taken an offer can be offered it again, so discounts cannot be stacked by reopening the cancellation flow.
135
+
106
136
  ## Refund a cancelled subscription
107
137
 
108
- Kelviq does not automatically refund unused time when a subscription is cancelled mid-period. You decide whether to issue a full refund, a partial refund, or no refund.
138
+ When a subscription is canceled mid-period, you decide whether to refund: in full, in part, or not at all.
109
139
 
110
- For a usage-based subscription, calculate the refund under your own policy using the customer's consumed usage and remaining time. Kelviq does not currently calculate usage-adjusted refunds for you. Once you decide the amount, open the corresponding order in the dashboard and issue the full or partial refund there.
140
+ For a usage-based subscription, work out the amount from the customer's usage and the time left. Then open the corresponding order in the dashboard and issue the full or partial refund there.
111
141
 
112
142
  ## Failed subscription payments
113
143
 
114
- A failed automatic card payment does not cancel the customer's payment authorization. Kelviq can use the same authorization for later attempts and future billing cycles.
144
+ After a failed card payment, the customer's authorization stays in place, so Kelviq can retry and bill future cycles.
115
145
 
116
146
  If the customer pays the failed card invoice manually, automatic payments remain active. Kelviq will still use the saved payment method for the next billing cycle.
117
147
 
@@ -123,4 +153,4 @@ After each failed attempt, Kelviq emails the customer a link to pay the invoice.
123
153
 
124
154
  You do not need to schedule retries, send card payment links, or ask the customer to set up automatic payments again. Kelviq handles this recovery flow.
125
155
 
126
- This retry schedule applies only to cards. Kelviq does not retry a failed non-card renewal or send a recovery payment link. The subscription is canceled after the payment fails.
156
+ Card and UPI AutoPay renewals follow this retry schedule. If the payment still hasn't gone through after 14 days, the subscription is canceled.
@@ -10,28 +10,28 @@ You manage your tax configuration in two places. You set how prices display on i
10
10
 
11
11
  By default Kelviq adds tax on top of your listed price at checkout. If you want customers to see the final price upfront you can enable tax inclusive pricing. You configure this per plan.
12
12
 
13
- <img height="400" src="/images/Tax-inclusive-drodown.png" />
13
+ <img src="/images/Tax-inclusive-drodown.webp" />
14
14
 
15
15
  To change how prices are displayed open your plan draft. Click the menu icon next to the Publish button and select Tax behavior.
16
16
 
17
- <img height="400" src="/images/tax-modal.png" />
17
+ <img src="/images/tax-modal.webp" />
18
18
 
19
19
  Toggle Include tax in prices to turn on inclusive pricing. Kelviq will ask you to select the specific currencies where the listed price should include tax.
20
20
 
21
- <img height="400" src="/images/select-countries-tax.png" />
21
+ <img src="/images/select-countries-tax.webp" />
22
22
 
23
- If you have just one default currency you will see just one default currency. This lets you mix billing styles on a single plan. You can select EUR to give European buyers an inclusive experience while leaving USD unchecked so North American buyers pay tax at checkout.
23
+ If the plan has only one currency, only that currency is listed. This lets you mix billing styles on a single plan. You can select EUR to give European buyers an inclusive experience while leaving USD unchecked so North American buyers pay tax at checkout.
24
24
 
25
25
  ## Business tax ID behavior
26
26
 
27
- When you sell to other businesses they are often exempt from paying sales tax or VAT. Kelviq handles this verification automatically. If a business enters a valid tax ID at checkout we apply a reverse charge and drop the tax requirement.
27
+ When a business customer enters a valid tax ID at checkout, Kelviq verifies it and applies the reverse charge, so no tax is added.
28
28
 
29
29
  If you enabled tax inclusive pricing in the steps above you need to tell Kelviq how to handle the final math for these exempt B2B customers.
30
30
 
31
- <img height="200" src="/images/tax-settings.png" />
31
+ Open **Settings → Tax settings**.
32
32
 
33
- Navigate to Settings in your sidebar and open the Tax settings page.
33
+ <img src="/images/tax-settings.webp" alt="The Tax settings page with the Business tax ID behavior toggle" />
34
34
 
35
35
  Turn on the Business tax ID behavior toggle. When this is active Kelviq automatically reduces the checkout total by the included tax amount if the customer enters a valid business tax ID.
36
36
 
37
- If you leave this disabled the checkout total remains the exact same and we attribute the extra margin directly to your account.
37
+ If it's off, the customer pays the same total and the tax portion goes to your balance.
@@ -4,7 +4,7 @@ slug: "product-catalog/usage-alerts"
4
4
  section: "product-catalog"
5
5
  description: "Configure usage thresholds and receive feature.usage_alert webhooks"
6
6
  ---
7
- Usage alerts tell your application when a customer's metered feature crosses a threshold. Use them with any meter feature, such as API calls, credits, tokens, or storage.
7
+ Usage alerts tell your application when a customer's Meter feature crosses a threshold. Use them with any Meter feature, such as API calls, credits, tokens, or storage.
8
8
 
9
9
  A usage alert has two parts. You configure the threshold on the plan, then receive the `feature.usage_alert` event through a webhook. Turning on the alert does not email the customer or show an in-app message by itself. Your webhook handler decides what happens next.
10
10
 
@@ -39,19 +39,19 @@ You can add more than one threshold. For example, use 75% for an early warning a
39
39
  ## Configure usage alerts in the dashboard
40
40
 
41
41
  1. Open **Product Catalog → Products** and select the product.
42
- 2. Open the plan that contains the metered feature.
43
- 3. Edit **Usage pricing** or open **Manage features & limits**.
44
- 4. Select the meter feature and enter its usage value or pricing configuration.
42
+ 2. Open the plan that contains the Meter feature.
43
+ 3. Edit **Usage charges** or open **Manage features & limits**.
44
+ 4. Select the Meter feature and enter its usage value or pricing configuration.
45
45
  5. Turn on **Usage alert**.
46
46
  6. Choose **Percentage** or **Balance** as the threshold type.
47
47
  7. Click **Add threshold** and enter each threshold.
48
48
  8. Save the configuration. If Kelviq creates a draft version of a published plan, publish the draft before testing it.
49
49
 
50
- <img height="400" src="/images/usage-alerts.png" />
50
+ <img src="/images/usage-alerts.webp" />
51
51
 
52
- If the Usage alert switch is disabled while managing an entitlement, make sure you selected a meter feature and entered a value. Percentage alerts also need a finite usage limit so Kelviq can calculate the percentage used.
52
+ If the Usage alert switch is disabled while managing an entitlement, make sure you selected a Meter feature and entered a value. Percentage alerts also need a finite usage limit so Kelviq can calculate the percentage used.
53
53
 
54
- Regional prices inherit usage alerts from the base price. Change the base price when the same alert configuration should apply to every regional price.
54
+ Localized prices inherit usage alerts from the base price. Change the base price when the same alert configuration should apply to every localized price.
55
55
 
56
56
  ## Configure usage alerts through the API
57
57