@kelviq/mcp-server 0.3.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -30
- package/dist/config.d.ts +5 -0
- package/dist/config.js +31 -10
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +84 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +134 -63
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +109 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -0
- package/dist/schemas/kelviq.js +50 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +15 -3
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +3 -0
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +8 -0
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.js +1 -0
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +5 -0
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +5 -1
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Pay as you go"
|
|
3
|
+
slug: "product-catalog/pay-as-you-go"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Bill customers each month for the usage they record"
|
|
6
|
+
---
|
|
7
|
+
With pay as you go, the customer does not buy a block of usage upfront. Your backend reports what they consume, and Kelviq bills the resulting amount at the end of the monthly subscription period. Use it for API calls, AI tokens, storage, compute time, or any other metered cost.
|
|
8
|
+
|
|
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
|
+
|
|
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.
|
|
12
|
+
|
|
13
|
+
## Before you start
|
|
14
|
+
|
|
15
|
+
You will need:
|
|
16
|
+
|
|
17
|
+
- A product and a plan in Kelviq
|
|
18
|
+
- A [Meter feature](/product-catalog/create-a-feature), such as `api-calls` or `tokens`
|
|
19
|
+
- A monthly price on the plan
|
|
20
|
+
- A server API key for the same environment as the plan
|
|
21
|
+
|
|
22
|
+
Pay as you go supports **Flat**, **Package**, **Tiered**, and **Volume** pricing. It does not support **Stair-step** pricing.
|
|
23
|
+
|
|
24
|
+
## Configure the plan
|
|
25
|
+
|
|
26
|
+
1. Open the product and edit its plan.
|
|
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.
|
|
29
|
+
4. For **Billing model**, choose **Pay-as-you-go**.
|
|
30
|
+
|
|
31
|
+
<img src="/images/select-billing-model.png" alt="Selecting Pay-as-you-go as the billing model in Kelviq" />
|
|
32
|
+
|
|
33
|
+
5. Choose a pricing model and enter its rates.
|
|
34
|
+
6. Add [usage alerts](/product-catalog/usage-alerts) if you want to notify your application when usage crosses a threshold.
|
|
35
|
+
7. Save the plan. If you edited a published plan, publish the new version before testing it.
|
|
36
|
+
|
|
37
|
+
When you select Pay as you go, Kelviq keeps Monthly as the plan's only billing period. Usage reset and credit rollover controls are removed because there is no prepaid balance to reset or carry into the next period.
|
|
38
|
+
|
|
39
|
+
## Choose a pricing model
|
|
40
|
+
|
|
41
|
+
The billing model controls *when* the customer pays. The pricing model controls *how* Kelviq calculates the charge.
|
|
42
|
+
|
|
43
|
+
| Pricing model | How it bills | Example |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
| Flat | Uses one rate for every unit | $0.001 per API call |
|
|
46
|
+
| Package | Bills in blocks of units | $2 per 10,000 tokens |
|
|
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 |
|
|
49
|
+
|
|
50
|
+
See [Usage based pricing](/product-catalog/usage-based-billing) for the full calculation rules and examples for each model.
|
|
51
|
+
|
|
52
|
+
### Combine a base price with usage
|
|
53
|
+
|
|
54
|
+
You can charge a fixed monthly subscription and add usage on top. For example:
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
Base subscription: $20 per month
|
|
58
|
+
Included usage: 100,000 tokens
|
|
59
|
+
Additional usage: $0.0002 per token
|
|
60
|
+
```
|
|
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.
|
|
63
|
+
|
|
64
|
+
## Report usage from your backend
|
|
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.
|
|
67
|
+
|
|
68
|
+
### Node.js
|
|
69
|
+
|
|
70
|
+
Use `DELTA` when each call adds to the current meter:
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import { BEHAVIOUR_CHOICES, Kelviq } from "@kelviq/node-sdk";
|
|
74
|
+
|
|
75
|
+
const client = new Kelviq({
|
|
76
|
+
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
await client.reporting.reportUsage({
|
|
80
|
+
customerId: "customer_001",
|
|
81
|
+
featureId: "api-calls",
|
|
82
|
+
value: 1,
|
|
83
|
+
behaviour: BEHAVIOUR_CHOICES.DELTA,
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Use `SET` when you already maintain a cumulative total and want Kelviq's meter to match it:
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
await client.reporting.reportUsage({
|
|
91
|
+
customerId: "customer_001",
|
|
92
|
+
featureId: "api-calls",
|
|
93
|
+
value: 1250,
|
|
94
|
+
behaviour: BEHAVIOUR_CHOICES.SET,
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
| Field | What to send |
|
|
99
|
+
| --- | --- |
|
|
100
|
+
| `customerId` | The same customer identifier used for the subscription |
|
|
101
|
+
| `featureId` | The identifier of the metered feature on the plan |
|
|
102
|
+
| `value` | A whole-number usage quantity |
|
|
103
|
+
| `behaviour` | `DELTA` to add usage or `SET` to replace the current value |
|
|
104
|
+
|
|
105
|
+
A repeated `DELTA` call adds the value again. Make sure retries do not submit the same unit of work twice. If your system periodically sends an authoritative running total, use `SET` instead.
|
|
106
|
+
|
|
107
|
+
### REST API
|
|
108
|
+
|
|
109
|
+
You can send the same update without an SDK:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
curl --request POST \
|
|
113
|
+
--url https://api.kelviq.com/api/v1/report/usage/ \
|
|
114
|
+
--header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
|
|
115
|
+
--header "Content-Type: application/json" \
|
|
116
|
+
--data '{
|
|
117
|
+
"customerId": "customer_001",
|
|
118
|
+
"featureId": "api-calls",
|
|
119
|
+
"value": 1,
|
|
120
|
+
"behaviour": "DELTA"
|
|
121
|
+
}'
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
See [Report pre-aggregated usage](/api-reference/reporting/report-pre-aggregated-usage) for the request and response schema.
|
|
125
|
+
|
|
126
|
+
## How billing works
|
|
127
|
+
|
|
128
|
+
1. The customer starts a monthly subscription.
|
|
129
|
+
2. Your backend reports usage throughout the period.
|
|
130
|
+
3. Kelviq updates the meter whenever it receives a valid report.
|
|
131
|
+
4. At the end of the subscription period, Kelviq applies the configured pricing rules to the final usage.
|
|
132
|
+
5. The meter starts a new monthly period on the customer's subscription renewal date.
|
|
133
|
+
|
|
134
|
+
Reporting usage does not charge the customer immediately. It updates the quantity Kelviq will use for the period's bill.
|
|
135
|
+
|
|
136
|
+
## Add alerts without stopping usage
|
|
137
|
+
|
|
138
|
+
Usage alerts are optional, but they are useful when a bill can grow during the month. You can set absolute thresholds for a pay-as-you-go feature, then handle the `feature.usage_alert` webhook to send an email, show an in-app warning, or suggest a different plan.
|
|
139
|
+
|
|
140
|
+
You do not need a separate pay-as-you-go webhook to calculate the bill. Usage reports drive the meter; alerts only notify your application when a threshold is crossed.
|
|
141
|
+
|
|
142
|
+
See [Usage alerts](/product-catalog/usage-alerts) for configuration and webhook examples.
|
|
143
|
+
|
|
144
|
+
## Test in sandbox
|
|
145
|
+
|
|
146
|
+
Sandbox and production have separate products, customers, subscriptions, and API keys. To test the complete flow:
|
|
147
|
+
|
|
148
|
+
1. Switch the dashboard to Sandbox.
|
|
149
|
+
2. Create or publish a monthly plan with a pay-as-you-go charge.
|
|
150
|
+
3. Complete a test checkout so the sandbox customer has an active subscription.
|
|
151
|
+
4. Initialize the Node SDK with `environment: "sandbox"`, or send REST requests to `https://sandboxapi.kelviq.com/api/v1`.
|
|
152
|
+
5. Report a small usage value.
|
|
153
|
+
6. Open the customer's metered entitlement and confirm that the recorded usage changed as expected.
|
|
154
|
+
|
|
155
|
+
See [Sandbox](/guides/sandbox) for environment setup and test-payment details.
|
|
156
|
+
|
|
157
|
+
## Troubleshooting
|
|
158
|
+
|
|
159
|
+
### Pay as you go shows a billing-period error
|
|
160
|
+
|
|
161
|
+
Remove every billing period except Monthly. A plan with both Monthly and Yearly pricing is not eligible, even if you only enter a usage rate under Monthly.
|
|
162
|
+
|
|
163
|
+
### Stair-step cannot be selected
|
|
164
|
+
|
|
165
|
+
Stair-step pricing is not available with Pay as you go. Choose Flat, Package, Tiered, or Volume. If you need fixed usage bands, use an advance commitment instead.
|
|
166
|
+
|
|
167
|
+
### Reported usage does not appear
|
|
168
|
+
|
|
169
|
+
Check that the API key, customer, plan, and feature all belong to the same environment. Also confirm that `customerId` and `featureId` exactly match the identifiers in Kelviq.
|
|
170
|
+
|
|
171
|
+
### Usage is too high
|
|
172
|
+
|
|
173
|
+
Look for duplicate `DELTA` calls or a mismatch between the unit your code reports and the unit your price expects. For package pricing, remember that a partially used package is billed as a complete package.
|
|
174
|
+
|
|
175
|
+
### Credit rollover is missing
|
|
176
|
+
|
|
177
|
+
This is expected. Rollover applies to unused advance-commitment credits, not usage billed after the period ends.
|
|
@@ -8,6 +8,8 @@ A plan is the commercial package you offer to customers. It bundles your pricing
|
|
|
8
8
|
|
|
9
9
|
You can create multiple plans for a single product. For example, you might have a "Starter" plan for hobbyists and a "Pro" plan for businesses.
|
|
10
10
|
|
|
11
|
+
For sales-led pricing, see [Create an Enterprise plan](/product-catalog/create-an-enterprise-plan). It covers both reusable Enterprise tiers and bespoke customer amounts.
|
|
12
|
+
|
|
11
13
|
## Plan structure
|
|
12
14
|
|
|
13
15
|
Every plan consists of configurable components that define what the user gets.
|
|
@@ -101,6 +103,8 @@ Once your plan draft exists you can configure how you charge. We split these int
|
|
|
101
103
|
|
|
102
104
|
* [One time payments](/product-catalog/one-time-payments)
|
|
103
105
|
* [Subscriptions](/product-catalog/subscriptions)
|
|
106
|
+
* [Enterprise and bespoke plans](/product-catalog/create-an-enterprise-plan)
|
|
107
|
+
* [Seat based pricing](/product-catalog/seat-based-pricing)
|
|
104
108
|
* [Usage based pricing](/product-catalog/usage-based-billing)
|
|
105
109
|
* [Free plans and trials](/product-catalog/free-and-trials)
|
|
106
110
|
* [Location based pricing](/product-catalog/location-based-pricing)
|
|
@@ -120,10 +124,16 @@ Select the intervals you want to offer. You can enable multiple intervals for a
|
|
|
120
124
|
|
|
121
125
|
<img height="200" src="/images/billing-cycle.png" />
|
|
122
126
|
|
|
127
|
+
* **28 days:** A recurring four-week subscription.
|
|
123
128
|
* **Monthly / Yearly:** Standard recurring subscriptions.
|
|
124
129
|
* **3 Months:** Quarterly billing.
|
|
130
|
+
* **6 Months:** Billing twice a year.
|
|
125
131
|
* **One time:** A single non-recurring payment (lifetime deal).
|
|
126
132
|
|
|
133
|
+
The 28-day period is useful when you need a consistent four-week renewal schedule rather than a calendar-month renewal.
|
|
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).
|
|
136
|
+
|
|
127
137
|
### Location based pricing
|
|
128
138
|
You can set specific prices for different countries rather than relying on auto-conversion.
|
|
129
139
|
1. Click **+ Add localized price**.
|
|
@@ -183,6 +193,10 @@ When you click **Publish**, we will ask you to confirm the rollout strategy.
|
|
|
183
193
|
* **For price changes:** You decide whether to grandfather existing users on the old price or migrate them to the new one.
|
|
184
194
|
* **For feature changes:** You decide whether to push the new entitlements to existing users immediately or keep them on their legacy configuration.
|
|
185
195
|
|
|
196
|
+
If you grandfather existing customers, they keep their current price and only new customers see the updated price. If you migrate existing customers, the new price applies to their future renewals.
|
|
197
|
+
|
|
198
|
+
Most recurring card and debit-card payments do not require the customer to approve the new price again. Some payment methods have additional rules. For example, an Indian UPI AutoPay mandate may require the customer to approve a renewal when the updated amount exceeds the applicable regulatory threshold.
|
|
199
|
+
|
|
186
200
|
If you change your mind while editing, you can click **Discard** to delete the unpublished version and revert to the live state.
|
|
187
201
|
|
|
188
202
|
### Plan actions
|
|
@@ -33,19 +33,11 @@ Follow these steps to set up a new product.
|
|
|
33
33
|
|
|
34
34
|
Fill out the basic information for your product.
|
|
35
35
|
|
|
36
|
-
* **Product name**
|
|
37
|
-
|
|
38
|
-
* **
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
You can override the auto-generated ID to match an existing ID in your internal database.
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
* **Description**
|
|
46
|
-
A short summary of the offering.
|
|
47
|
-
* **Media**
|
|
48
|
-
Upload up to 10 images to showcase the product on your checkout page. We recommend a 4:3 aspect ratio (1600 x 1200px).
|
|
36
|
+
* **Product name** — The public name shown to customers, such as “Pro Templates”.
|
|
37
|
+
* **Description** — A short summary of the offering.
|
|
38
|
+
* **Media** — Upload up to 10 images to showcase the product on checkout. We recommend a 4:3 aspect ratio (1600 × 1200 px).
|
|
39
|
+
|
|
40
|
+
Kelviq assigns an internal UUID when the product is created. You do not need to create or manage a separate product identifier in the dashboard.
|
|
49
41
|
|
|
50
42
|
|
|
51
43
|
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Seat based pricing"
|
|
3
|
+
slug: "product-catalog/seat-based-pricing"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Charge teams for the number of seats they purchase"
|
|
6
|
+
---
|
|
7
|
+
Seat based pricing ties the subscription price to the number of people who can use an account. A team that buys eight seats pays for eight, even if only six are occupied today.
|
|
8
|
+
|
|
9
|
+
This guide covers seats purchased in advance. The chosen quantity is included when you create checkout, and your application uses the resulting entitlement as its team-size limit.
|
|
10
|
+
|
|
11
|
+
If you want to bill for the number of seats that were actually active during the month, use [pay as you go](/product-catalog/pay-as-you-go) instead. Report the active-seat total with `SET` and let Kelviq bill it at the end of the period.
|
|
12
|
+
|
|
13
|
+
## How the price is calculated
|
|
14
|
+
|
|
15
|
+
A plan can consist entirely of seat charges or combine them with a fixed base price.
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
Monthly base price: $20
|
|
19
|
+
Price per seat: $12
|
|
20
|
+
Seats purchased: 8
|
|
21
|
+
|
|
22
|
+
Monthly subtotal: $20 + ($12 × 8) = $116
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Kelviq carries the seat quantity from checkout into the subscription. The resulting entitlement tells your application how many seats the customer purchased.
|
|
26
|
+
|
|
27
|
+
## Create the seat feature
|
|
28
|
+
|
|
29
|
+
These steps create a Meter feature specifically for seats. For the general dashboard and API workflows, see [Create a feature in Kelviq](/product-catalog/create-a-feature).
|
|
30
|
+
|
|
31
|
+
1. Open **Product catalog → Features**.
|
|
32
|
+
2. Click **Create feature**.
|
|
33
|
+
3. Enter a clear name such as `Seats`.
|
|
34
|
+
4. Use a stable identifier such as `seats`.
|
|
35
|
+
5. Select **Meter** as the feature type.
|
|
36
|
+
6. Set the singular unit to `seat` and the plural unit to `seats`.
|
|
37
|
+
7. Create the feature.
|
|
38
|
+
|
|
39
|
+
Use a Meter feature rather than a Customizable feature. Kelviq can attach a price to the Meter feature and accept its quantity during checkout.
|
|
40
|
+
|
|
41
|
+
Purchased-seat pricing does not require usage reports. Although Seats is a Meter feature, its billable quantity comes from checkout and subscription updates.
|
|
42
|
+
|
|
43
|
+
## Add the seat price to a plan
|
|
44
|
+
|
|
45
|
+
1. Open the product and edit the plan you want to sell.
|
|
46
|
+
2. Make the plan **Paid** and select its billing periods, such as Monthly and Yearly.
|
|
47
|
+
3. Enter the plan's base price. Use this for the fixed part of the subscription, if any.
|
|
48
|
+
4. Open **Usage charges**.
|
|
49
|
+
|
|
50
|
+
<img src="/images/usage-pricing-card.png" alt="Usage charges section for API requests or seats in Kelviq" />
|
|
51
|
+
|
|
52
|
+
5. Select the `seats` feature.
|
|
53
|
+
6. For **Billing model**, choose **Advance commitment**. The customer is purchasing the seats before using them.
|
|
54
|
+
7. For **Pricing model**, choose **Flat** for a standard per-seat price.
|
|
55
|
+
8. Enter the price per unit for every billing period. For example, use `$12` under Monthly and `$120` under Yearly.
|
|
56
|
+
9. Save the price and publish the plan.
|
|
57
|
+
|
|
58
|
+
<img src="/images/select-billing-model.png" alt="Advance commitment and Pay-as-you-go billing model options in Kelviq" />
|
|
59
|
+
|
|
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
|
+
|
|
62
|
+
## Other ways to price seats
|
|
63
|
+
|
|
64
|
+
Most teams start with one price per seat. You can also sell seats in packages, lower the rate at higher quantities, or charge a fixed amount for each range.
|
|
65
|
+
|
|
66
|
+
| Pricing model | Seat calculation | Example |
|
|
67
|
+
| --- | --- | --- |
|
|
68
|
+
| Flat | Every seat has the same price | 8 seats × $12 = $96 |
|
|
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 |
|
|
73
|
+
|
|
74
|
+
See [Usage based pricing](/product-catalog/usage-based-billing) for the calculation rules for Package, Tiered, Volume, and Stair-step pricing.
|
|
75
|
+
|
|
76
|
+
## Send the seat count to checkout
|
|
77
|
+
|
|
78
|
+
Kelviq's pricing UI can show a quantity input for a priced Meter feature. If you build your own pricing page, send the selected seat count in the checkout request.
|
|
79
|
+
|
|
80
|
+
### Node.js
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import { CHARGE_PERIOD_CHOICES, Kelviq } from "@kelviq/node-sdk";
|
|
84
|
+
|
|
85
|
+
const client = new Kelviq({
|
|
86
|
+
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
const seatCount = 8;
|
|
90
|
+
|
|
91
|
+
const session = await client.checkout.createSession({
|
|
92
|
+
planIdentifier: "team-plan",
|
|
93
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
94
|
+
customerId: "customer_001",
|
|
95
|
+
successUrl: "https://app.example.com/billing/success",
|
|
96
|
+
features: [
|
|
97
|
+
{
|
|
98
|
+
identifier: "seats",
|
|
99
|
+
quantity: seatCount,
|
|
100
|
+
},
|
|
101
|
+
],
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
return Response.redirect(session.checkoutUrl);
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### REST API
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
curl --request POST \
|
|
111
|
+
--url https://api.kelviq.com/api/v1/checkout/ \
|
|
112
|
+
--header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
|
|
113
|
+
--header "Content-Type: application/json" \
|
|
114
|
+
--data '{
|
|
115
|
+
"planIdentifier": "team-plan",
|
|
116
|
+
"chargePeriod": "MONTHLY",
|
|
117
|
+
"customerId": "customer_001",
|
|
118
|
+
"successUrl": "https://app.example.com/billing/success",
|
|
119
|
+
"features": [
|
|
120
|
+
{
|
|
121
|
+
"identifier": "seats",
|
|
122
|
+
"quantity": 8
|
|
123
|
+
}
|
|
124
|
+
]
|
|
125
|
+
}'
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The `features` array uses the feature identifier, not its dashboard UUID. `quantity` is the number of seats the customer wants to purchase.
|
|
129
|
+
|
|
130
|
+
Create the checkout session on your backend. Validate that the quantity is a positive whole number, and never expose the Server API Key in browser code.
|
|
131
|
+
|
|
132
|
+
See [Create a checkout session](/api-reference/checkout/create-a-checkout-session) for the full request schema.
|
|
133
|
+
|
|
134
|
+
## Enforce the purchased limit
|
|
135
|
+
|
|
136
|
+
After payment and subscription creation, read the customer's seat entitlement from your backend. For a Meter feature, `usageLimit` is the purchased capacity.
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
const entitlement = await client.entitlements.getEntitlement({
|
|
140
|
+
customerId: "customer_001",
|
|
141
|
+
featureId: "seats",
|
|
142
|
+
});
|
|
143
|
+
|
|
144
|
+
const purchasedSeats = entitlement?.usageLimit ?? 0;
|
|
145
|
+
const activeMembers = await db.teamMember.count({
|
|
146
|
+
where: { teamId: "team_001", status: "active" },
|
|
147
|
+
});
|
|
148
|
+
|
|
149
|
+
if (activeMembers >= purchasedSeats) {
|
|
150
|
+
throw new Error("No seats available. Add another seat before inviting a member.");
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Check the limit when the team owner sends or accepts an invitation. A frontend-only check is easy to bypass, so keep the final enforcement on your server.
|
|
155
|
+
|
|
156
|
+
`hasAccess` answers whether the customer can use the feature. It does not tell you whether one more team member fits. Compare your active member count with `usageLimit` for that decision.
|
|
157
|
+
|
|
158
|
+
## Change the seat count
|
|
159
|
+
|
|
160
|
+
Use the subscription update endpoint when a customer adds or removes seats. Send the complete new quantity, not the difference from the old quantity.
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
import { CHARGE_PERIOD_CHOICES } from "@kelviq/node-sdk";
|
|
164
|
+
|
|
165
|
+
await client.subscriptions.update({
|
|
166
|
+
subscriptionId: "dffaf07e-4517-47db-ba3a-59a05aa2d465",
|
|
167
|
+
planIdentifier: "team-plan",
|
|
168
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
169
|
+
features: [
|
|
170
|
+
{
|
|
171
|
+
identifier: "seats",
|
|
172
|
+
quantity: 12,
|
|
173
|
+
},
|
|
174
|
+
],
|
|
175
|
+
});
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The update request still needs `planIdentifier` and `chargePeriod`, even when the plan is not changing. After the request succeeds, read the entitlement again before making the additional capacity available.
|
|
179
|
+
|
|
180
|
+
Before reducing a subscription below the current team size, ask the customer to remove or deactivate members. Otherwise, the subscription and your application's active-member count will disagree.
|
|
181
|
+
|
|
182
|
+
See [Update a subscription](/api-reference/subscriptions/update-a-subscription) for the complete API request.
|
|
183
|
+
|
|
184
|
+
## Purchased seats versus active seats
|
|
185
|
+
|
|
186
|
+
Choose one source of truth for billing.
|
|
187
|
+
|
|
188
|
+
| Model | Where the quantity comes from | When the customer pays |
|
|
189
|
+
| --- | --- | --- |
|
|
190
|
+
| Purchased seats | Checkout and subscription updates | At the start of the billing period |
|
|
191
|
+
| Active seats | Usage reported by your backend | At the end of each monthly period |
|
|
192
|
+
|
|
193
|
+
For active-seat billing, configure the Seats feature as Pay as you go and send the current active-seat total with `SET`. Do not send both a purchased quantity and usage reports for the same seat charge, or the two models will conflict.
|
|
194
|
+
|
|
195
|
+
## Seats are not license activations
|
|
196
|
+
|
|
197
|
+
A seat normally represents a member of a team or workspace. A license activation represents a device or software installation.
|
|
198
|
+
|
|
199
|
+
Use seat based pricing when the customer pays for people who can join an account. Use [license keys](/product-catalog/license-keys) when you need to limit how many devices can activate downloaded software. A single customer may use both, but they should have separate limits.
|
|
200
|
+
|
|
201
|
+
## Test in sandbox
|
|
202
|
+
|
|
203
|
+
1. Switch the dashboard to Sandbox.
|
|
204
|
+
2. Create the Seats feature and a seat based plan there.
|
|
205
|
+
3. Create a checkout session with a small quantity, such as 3.
|
|
206
|
+
4. Confirm that checkout shows the expected base and seat charges.
|
|
207
|
+
5. Complete the test payment.
|
|
208
|
+
6. Read the `seats` entitlement and confirm that its limit matches the purchased quantity.
|
|
209
|
+
7. Update the subscription to 5 seats and check the entitlement again.
|
|
210
|
+
|
|
211
|
+
Sandbox and production use separate catalog data and API keys. See [Sandbox](/guides/sandbox) before moving the integration to production.
|
|
212
|
+
|
|
213
|
+
## Troubleshooting
|
|
214
|
+
|
|
215
|
+
### The total does not change with the seat count
|
|
216
|
+
|
|
217
|
+
Confirm that Seats is a Meter feature, that it has a price under Usage charges, and that the checkout request includes the exact `seats` identifier in `features`.
|
|
218
|
+
|
|
219
|
+
### The quantity input is missing
|
|
220
|
+
|
|
221
|
+
Publish the latest version of the plan and check that the seat feature is enabled and priced for the selected billing period.
|
|
222
|
+
|
|
223
|
+
### The entitlement has the wrong limit
|
|
224
|
+
|
|
225
|
+
Check that the checkout, customer, plan, and API key belong to the same environment. Then inspect the checkout or subscription request and confirm that `quantity` contains the complete desired seat count.
|
|
226
|
+
|
|
227
|
+
### A team can exceed its purchased seats
|
|
228
|
+
|
|
229
|
+
Kelviq stores the entitlement, but your application must enforce it when members are invited or activated. Compare the active-member count with `usageLimit` on your backend.
|
|
230
|
+
|
|
231
|
+
### A seat reduction would leave too many active members
|
|
232
|
+
|
|
233
|
+
Do not remove members automatically unless your product explicitly promises that behavior. Ask a team owner to choose which members lose access, then submit the lower quantity.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
title: "Subscriptions"
|
|
3
3
|
slug: "product-catalog/subscriptions"
|
|
4
4
|
section: "product-catalog"
|
|
5
|
-
description: "Set up
|
|
5
|
+
description: "Set up recurring billing and understand renewals and failed payments"
|
|
6
6
|
---
|
|
7
7
|
Subscriptions are the default for traditional SaaS products. You charge customers on a regular schedule to maintain access to your application.
|
|
8
8
|
|
|
@@ -10,20 +10,117 @@ Subscriptions are the default for traditional SaaS products. You charge customer
|
|
|
10
10
|
|
|
11
11
|
<img height="200" src="/images/subscription-pricing.png" />
|
|
12
12
|
|
|
13
|
-
1. Open
|
|
14
|
-
2. Under
|
|
15
|
-
3. Enter the price for each interval
|
|
16
|
-
4. Click Save
|
|
13
|
+
1. Open a draft plan and make sure it is set to **Paid**.
|
|
14
|
+
2. Under **Billing cycles**, select the recurring intervals you want to offer, such as **28 days**, **Monthly**, **3 Months**, **6 Months**, or **Yearly**.
|
|
15
|
+
3. Enter the price for each interval.
|
|
16
|
+
4. Click **Save**.
|
|
17
17
|
|
|
18
|
-
You can enable multiple intervals on
|
|
18
|
+
You can enable multiple intervals on one plan. Customers choose among the enabled intervals at checkout.
|
|
19
|
+
|
|
20
|
+
A 28-day subscription renews every four weeks. It is not the same as a calendar-month subscription. If the **28 days** option is not visible for your organization, contact Kelviq support to have it enabled.
|
|
19
21
|
|
|
20
22
|
## Subscription lifecycle
|
|
21
23
|
|
|
22
|
-
Kelviq handles
|
|
24
|
+
Kelviq handles recurring payments automatically. This includes:
|
|
25
|
+
|
|
26
|
+
* Charging the saved payment method at the end of each billing cycle
|
|
27
|
+
* Sending receipts and tax invoices
|
|
28
|
+
* Retrying failed card payments
|
|
29
|
+
* Applying prorated charges when a customer changes plans during a billing cycle
|
|
30
|
+
|
|
31
|
+
Check the current subscription status with the Kelviq SDK or API. If your application needs event notifications, use [webhooks](/guides/webhooks).
|
|
32
|
+
|
|
33
|
+
## Change a subscription
|
|
34
|
+
|
|
35
|
+
By default, plan upgrades and downgrades take effect immediately. As soon as the change is processed, Kelviq applies the new plan and its feature limits.
|
|
36
|
+
|
|
37
|
+
For a paid change, you can wait until payment succeeds before activating the new plan. Pass `paymentBehavior: "activate_on_payment"` when you update the subscription:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"planIdentifier": "premium-plan",
|
|
42
|
+
"chargePeriod": "MONTHLY",
|
|
43
|
+
"paymentBehavior": "activate_on_payment"
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Omit `paymentBehavior` to keep the default immediate-update behavior.
|
|
48
|
+
|
|
49
|
+
### Control how a change is billed
|
|
50
|
+
|
|
51
|
+
Pass `prorationBehavior` when you update a subscription to choose when the customer pays for a mid-period change:
|
|
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.
|
|
64
|
+
|
|
65
|
+
### Wait for payment before changing access
|
|
66
|
+
|
|
67
|
+
`activate_on_payment` keeps the customer's current subscription active while payment for the change is pending. This prevents an unpaid plan change from replacing working access.
|
|
68
|
+
|
|
69
|
+
| Payment stage | Current subscription | Updated subscription |
|
|
70
|
+
| --- | --- | --- |
|
|
71
|
+
| A saved card is charged successfully without customer action | Changes to `superseded` | Changes to `active` |
|
|
72
|
+
| UPI, a 3DS card, or another method requires customer action | Remains `active` | Starts as `incomplete` |
|
|
73
|
+
| The customer completes payment | Changes to `superseded` | Changes to `active` |
|
|
74
|
+
| The immediate charge fails, or the customer does not complete payment before expiry | Remains `active` | Changes to `incomplete_expired` |
|
|
75
|
+
|
|
76
|
+
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
|
+
|
|
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.
|
|
79
|
+
|
|
80
|
+
### Upgrades
|
|
81
|
+
|
|
82
|
+
Under the default `IMMEDIATE_CHARGE` proration behavior, Kelviq prorates the price change against the time left in the current billing period. It credits the unused portion of the old plan, charges for the remaining portion of the new plan, and collects the net difference. See [Control how a change is billed](#control-how-a-change-is-billed) for the other options.
|
|
83
|
+
|
|
84
|
+
With `activate_on_payment`, Kelviq waits for that payment to succeed before activating the upgraded plan.
|
|
85
|
+
|
|
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:
|
|
87
|
+
|
|
88
|
+
| Item | Amount |
|
|
89
|
+
| --- | ---: |
|
|
90
|
+
| Unused half of the old plan | -$50 credit |
|
|
91
|
+
| Remaining half of the new plan | $100 charge |
|
|
92
|
+
| Net amount collected | $50 |
|
|
93
|
+
|
|
94
|
+
The exact amount depends on when the upgrade is processed. Existing usage counters are retained and evaluated against the new plan's limits.
|
|
95
|
+
|
|
96
|
+
### Downgrades
|
|
97
|
+
|
|
98
|
+
Under the default payment behavior, downgrades also apply immediately. If the customer has unused value on the higher-priced plan, Kelviq converts it to account credit and applies that credit to future invoices.
|
|
99
|
+
|
|
100
|
+
An immediate downgrade can lower a customer's limits below their current usage. Check the customer's entitlements after the change and decide how your application should handle any over-limit state.
|
|
101
|
+
|
|
102
|
+
## Cancel a subscription
|
|
103
|
+
|
|
104
|
+
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
|
+
|
|
106
|
+
## Refund a cancelled subscription
|
|
107
|
+
|
|
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.
|
|
109
|
+
|
|
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.
|
|
111
|
+
|
|
112
|
+
## Failed subscription payments
|
|
113
|
+
|
|
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.
|
|
115
|
+
|
|
116
|
+
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
|
+
|
|
118
|
+
### Card payment retries
|
|
119
|
+
|
|
120
|
+
When an automatic card payment fails, the subscription moves to `past_due`. Kelviq retries the payment up to eight times over the next 14 days. If recovery is unsuccessful, Kelviq cancels the subscription.
|
|
121
|
+
|
|
122
|
+
After each failed attempt, Kelviq emails the customer a link to pay the invoice. The customer can also use the [Customer Portal](/customer-portal/managing-payment-methods) to update their payment method.
|
|
23
123
|
|
|
24
|
-
|
|
25
|
-
* Sending automated email receipts and tax invoices
|
|
26
|
-
* Handling failed payments with built in retries
|
|
27
|
-
* Prorating upgrades and downgrades if the user switches plans mid cycle
|
|
124
|
+
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.
|
|
28
125
|
|
|
29
|
-
|
|
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.
|