@kelviq/mcp-server 0.2.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/LICENSE +21 -0
- package/README.md +322 -0
- package/dist/config.d.ts +16 -0
- package/dist/config.js +45 -0
- package/dist/config.js.map +1 -0
- package/dist/docs/README.md +128 -0
- package/dist/docs/api-reference/authentication.md +41 -0
- package/dist/docs/backend-integration/node-sdk.md +1040 -0
- package/dist/docs/backend-integration/python-sdk.md +1198 -0
- package/dist/docs/changelog/app.md +80 -0
- package/dist/docs/changelog/checkout-api.md +59 -0
- package/dist/docs/changelog/js-promotions-ui.md +14 -0
- package/dist/docs/changelog/js-sdk.md +281 -0
- package/dist/docs/changelog/node-sdk.md +378 -0
- package/dist/docs/changelog/python-sdk.md +456 -0
- package/dist/docs/changelog/react-sdk.md +580 -0
- package/dist/docs/checkout/checkout-configuration.md +434 -0
- package/dist/docs/coustomers-management/overview.md +111 -0
- package/dist/docs/customer-portal/overview.md +81 -0
- package/dist/docs/frontend-integration/js-sdk.md +676 -0
- package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
- package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
- package/dist/docs/frontend-integration/react-sdk.md +1187 -0
- package/dist/docs/frontend-integration/react-ui.md +771 -0
- package/dist/docs/getstarted/fees.md +160 -0
- package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
- package/dist/docs/getstarted/merchant-of-record.md +64 -0
- package/dist/docs/getstarted/review-process.md +190 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
- package/dist/docs/guides/subscription-integration.md +291 -0
- package/dist/docs/guides/webhooks.md +963 -0
- package/dist/docs/legal/approved-prohibited-policy.md +252 -0
- package/dist/docs/legal/buyer-terms.md +177 -0
- package/dist/docs/legal/compliant-user-flow.md +216 -0
- package/dist/docs/legal/master-service-agreement.md +404 -0
- package/dist/docs/legal/payment-flow-diagram.md +188 -0
- package/dist/docs/legal/seller-terms.md +169 -0
- package/dist/docs/manifest.json +415 -0
- package/dist/docs/monetization/offerings.md +156 -0
- package/dist/docs/monetization/pricing-tables.md +226 -0
- package/dist/docs/monetization/targeting-rules.md +278 -0
- package/dist/docs/openapi.json +5479 -0
- package/dist/docs/payouts/overview.md +43 -0
- package/dist/docs/payouts/payout-account.md +12 -0
- package/dist/docs/payouts/transactions.md +23 -0
- package/dist/docs/product-catalog/digital-downloads.md +117 -0
- package/dist/docs/product-catalog/discounts.md +69 -0
- package/dist/docs/product-catalog/entitlements.md +428 -0
- package/dist/docs/product-catalog/free-and-trials.md +36 -0
- package/dist/docs/product-catalog/license-keys.md +324 -0
- package/dist/docs/product-catalog/links.md +92 -0
- package/dist/docs/product-catalog/location-based-pricing.md +41 -0
- package/dist/docs/product-catalog/one-time-payments.md +24 -0
- package/dist/docs/product-catalog/plans.md +199 -0
- package/dist/docs/product-catalog/products.md +60 -0
- package/dist/docs/product-catalog/subscriptions.md +29 -0
- package/dist/docs/product-catalog/tax-settings.md +37 -0
- package/dist/docs/product-catalog/usage-based-billing.md +119 -0
- package/dist/docs/promotions/create-a-promotion.md +75 -0
- package/dist/docs/promotions/customize-banner.md +41 -0
- package/dist/docs/promotions/integrate.md +38 -0
- package/dist/docs/promotions/overview.md +51 -0
- package/dist/docs/quickstart/core-concepts.md +146 -0
- package/dist/docs/quickstart/dashboard-setup.md +129 -0
- package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
- package/dist/docs/sales/checkout-sessions.md +58 -0
- package/dist/docs/sales/orders.md +76 -0
- package/dist/http/client.d.ts +28 -0
- package/dist/http/client.js +76 -0
- package/dist/http/client.js.map +1 -0
- package/dist/http/errors.d.ts +20 -0
- package/dist/http/errors.js +58 -0
- package/dist/http/errors.js.map +1 -0
- package/dist/resources/docs-index.d.ts +25 -0
- package/dist/resources/docs-index.js +109 -0
- package/dist/resources/docs-index.js.map +1 -0
- package/dist/resources/index.d.ts +2 -0
- package/dist/resources/index.js +73 -0
- package/dist/resources/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +1304 -0
- package/dist/schemas/kelviq.js +468 -0
- package/dist/schemas/kelviq.js.map +1 -0
- package/dist/server.d.ts +2 -0
- package/dist/server.js +41 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/_util.d.ts +15 -0
- package/dist/tools/_util.js +15 -0
- package/dist/tools/_util.js.map +1 -0
- package/dist/tools/checkout.d.ts +3 -0
- package/dist/tools/checkout.js +18 -0
- package/dist/tools/checkout.js.map +1 -0
- package/dist/tools/customers.d.ts +3 -0
- package/dist/tools/customers.js +32 -0
- package/dist/tools/customers.js.map +1 -0
- package/dist/tools/docs.d.ts +2 -0
- package/dist/tools/docs.js +43 -0
- package/dist/tools/docs.js.map +1 -0
- package/dist/tools/entitlements.d.ts +3 -0
- package/dist/tools/entitlements.js +22 -0
- package/dist/tools/entitlements.js.map +1 -0
- package/dist/tools/features.d.ts +3 -0
- package/dist/tools/features.js +55 -0
- package/dist/tools/features.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.js +44 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/licenses.d.ts +3 -0
- package/dist/tools/licenses.js +44 -0
- package/dist/tools/licenses.js.map +1 -0
- package/dist/tools/media.d.ts +3 -0
- package/dist/tools/media.js +18 -0
- package/dist/tools/media.js.map +1 -0
- package/dist/tools/offerings.d.ts +3 -0
- package/dist/tools/offerings.js +21 -0
- package/dist/tools/offerings.js.map +1 -0
- package/dist/tools/partner.d.ts +3 -0
- package/dist/tools/partner.js +55 -0
- package/dist/tools/partner.js.map +1 -0
- package/dist/tools/plan-entitlements.d.ts +3 -0
- package/dist/tools/plan-entitlements.js +56 -0
- package/dist/tools/plan-entitlements.js.map +1 -0
- package/dist/tools/plan-files.d.ts +3 -0
- package/dist/tools/plan-files.js +43 -0
- package/dist/tools/plan-files.js.map +1 -0
- package/dist/tools/plans.d.ts +3 -0
- package/dist/tools/plans.js +120 -0
- package/dist/tools/plans.js.map +1 -0
- package/dist/tools/portal.d.ts +3 -0
- package/dist/tools/portal.js +18 -0
- package/dist/tools/portal.js.map +1 -0
- package/dist/tools/product-files.d.ts +3 -0
- package/dist/tools/product-files.js +31 -0
- package/dist/tools/product-files.js.map +1 -0
- package/dist/tools/product-settings.d.ts +3 -0
- package/dist/tools/product-settings.js +31 -0
- package/dist/tools/product-settings.js.map +1 -0
- package/dist/tools/products.d.ts +3 -0
- package/dist/tools/products.js +69 -0
- package/dist/tools/products.js.map +1 -0
- package/dist/tools/promotions.d.ts +3 -0
- package/dist/tools/promotions.js +19 -0
- package/dist/tools/promotions.js.map +1 -0
- package/dist/tools/subscriptions.d.ts +3 -0
- package/dist/tools/subscriptions.js +63 -0
- package/dist/tools/subscriptions.js.map +1 -0
- package/dist/tools/usage.d.ts +3 -0
- package/dist/tools/usage.js +18 -0
- package/dist/tools/usage.js.map +1 -0
- package/package.json +88 -0
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Plans"
|
|
3
|
+
slug: "product-catalog/plans"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Configure pricing, features, and deliverables"
|
|
6
|
+
---
|
|
7
|
+
A plan is the commercial package you offer to customers. It bundles your pricing logic with the actual value you deliver, such as software downloads, community access, or feature limits.
|
|
8
|
+
|
|
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
|
+
|
|
11
|
+
## Plan structure
|
|
12
|
+
|
|
13
|
+
Every plan consists of configurable components that define what the user gets.
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
Define the cost. Choose between recurring subscriptions (monthly/yearly) or one-time lifetime payments.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
Issue software licenses. Generate unique keys upon purchase and enforce activation limits.
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
Set limits. Control access to specific features, API quotas, or seat limits via the SDK.
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
Attach files. Upload software binaries, e-books, or course content.
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
Grant access. Direct customers to private Discord servers or Notion templates.
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## Plan lifecycle
|
|
41
|
+
|
|
42
|
+
You manage plans through a simple status flow.
|
|
43
|
+
|
|
44
|
+
* **Draft**
|
|
45
|
+
The default state for new plans. These are not visible to customers.
|
|
46
|
+
* **Published**
|
|
47
|
+
The plan is live and checkout is enabled.
|
|
48
|
+
* **Unpublished changes**
|
|
49
|
+
A draft version of an existing published plan. You are editing a copy, so your live plan remains safe until you hit publish again.
|
|
50
|
+
* **Archived**
|
|
51
|
+
The plan is hidden from new customers but remains active for existing subscribers.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Create a plan
|
|
56
|
+
|
|
57
|
+
You create plans directly inside a product container.
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
Navigate to the **Product detail page** and click **+ Create plan**.
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
<img height="200" src="/images/create-plan.png" />
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
Fill in the plan details.
|
|
72
|
+
* **Plan name:** The public name (e.g. "Pro", "Starter").
|
|
73
|
+
* **Identifier:** The unique ID used in your code. You can override the auto-generated ID.
|
|
74
|
+
* **Description:** Optional text shown on invoices and checkout.
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
<img height="200" src="/images/create-plan-modal.png" />
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
Enable the **Create more** toggle to quickly add multiple plans in a row without closing the modal.
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
Click **Create**. The plan will appear in your list with a **Draft** badge.
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Configure pricing
|
|
95
|
+
|
|
96
|
+
Click on any draft plan to enter the configuration view. The first step is to set how you charge.
|
|
97
|
+
|
|
98
|
+
## Pricing models
|
|
99
|
+
|
|
100
|
+
Once your plan draft exists you can configure how you charge. We split these into dedicated guides.
|
|
101
|
+
|
|
102
|
+
* [One time payments](/product-catalog/one-time-payments)
|
|
103
|
+
* [Subscriptions](/product-catalog/subscriptions)
|
|
104
|
+
* [Usage based pricing](/product-catalog/usage-based-billing)
|
|
105
|
+
* [Free plans and trials](/product-catalog/free-and-trials)
|
|
106
|
+
* [Location based pricing](/product-catalog/location-based-pricing)
|
|
107
|
+
|
|
108
|
+
<img height="200" src="/images/configure-price.png" />
|
|
109
|
+
|
|
110
|
+
### Free vs. Paid
|
|
111
|
+
Use the toggle in the top right to switch between a free or paid plan.
|
|
112
|
+
|
|
113
|
+
<img height="200" src="/images/free-paid.png" />
|
|
114
|
+
|
|
115
|
+
* **Free plan:** Users are not charged. Useful for lead magnets or open-source tiers.
|
|
116
|
+
* **Paid plan:** Unlocks the billing configuration options below.
|
|
117
|
+
|
|
118
|
+
### Billing cycles
|
|
119
|
+
Select the intervals you want to offer. You can enable multiple intervals for a single plan.
|
|
120
|
+
|
|
121
|
+
<img height="200" src="/images/billing-cycle.png" />
|
|
122
|
+
|
|
123
|
+
* **Monthly / Yearly:** Standard recurring subscriptions.
|
|
124
|
+
* **3 Months:** Quarterly billing.
|
|
125
|
+
* **One time:** A single non-recurring payment (lifetime deal).
|
|
126
|
+
|
|
127
|
+
### Location based pricing
|
|
128
|
+
You can set specific prices for different countries rather than relying on auto-conversion.
|
|
129
|
+
1. Click **+ Add localized price**.
|
|
130
|
+
2. Select the currency (e.g. EUR, INR).
|
|
131
|
+
3. Enter the price for that market.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Add deliverables
|
|
136
|
+
|
|
137
|
+
Configure what the customer receives immediately after purchase. These assets are delivered directly via the customer portal or email.
|
|
138
|
+
|
|
139
|
+
### Digital downloads
|
|
140
|
+
Upload files that are securely delivered after purchase.
|
|
141
|
+
1. Expand the **Digital downloads** accordion.
|
|
142
|
+
2. Drag and drop your files (up to 5GB total).
|
|
143
|
+
3. Customers will see these in their portal immediately after checkout.
|
|
144
|
+
|
|
145
|
+
### License keys
|
|
146
|
+
If you are selling software that requires activation, you can issue unique license keys.
|
|
147
|
+
1. Expand the **License keys** accordion.
|
|
148
|
+
2. **Activation limit:** Set how many machines or instances can use a single key (e.g. 1 for personal, 5 for team).
|
|
149
|
+
3. **License duration:** Define how long the key remains valid (e.g. 1 Year).
|
|
150
|
+
|
|
151
|
+
### External links
|
|
152
|
+
Provide access to resources hosted elsewhere.
|
|
153
|
+
1. Expand the **Links** accordion.
|
|
154
|
+
2. Add the **Link name** (e.g. Private Discord community).
|
|
155
|
+
3. Add the **Link URL**.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Feature & limits
|
|
160
|
+
Configure feature access, usage quotas, and API limits.
|
|
161
|
+
|
|
162
|
+
* **Toggle features:** Turn specific capabilities on or off (e.g. "SSO Access").
|
|
163
|
+
* **Numeric limits:** Set quotas (e.g. "5 Projects", "10,000 API calls").
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Publishing & Versioning
|
|
168
|
+
|
|
169
|
+
We protect your live customers by creating a separate version when you edit a plan.
|
|
170
|
+
|
|
171
|
+
### How it works
|
|
172
|
+
* **Safe editing**
|
|
173
|
+
When you edit a **Published** plan, we automatically create a new **Unpublished** version. Your live plan remains untouched so customers can keep buying without interruption.
|
|
174
|
+
* **Unpublished changes**
|
|
175
|
+
You will see a yellow badge indicating you are working on a draft version. You can make as many changes as you want here without affecting the live site.
|
|
176
|
+
* **Publishing**
|
|
177
|
+
When you click **Publish**, this new version replaces the old one.
|
|
178
|
+
|
|
179
|
+
### Pushing updates
|
|
180
|
+
Because the new version replaces the old one, you need to decide what happens to your current subscribers.
|
|
181
|
+
|
|
182
|
+
When you click **Publish**, we will ask you to confirm the rollout strategy.
|
|
183
|
+
* **For price changes:** You decide whether to grandfather existing users on the old price or migrate them to the new one.
|
|
184
|
+
* **For feature changes:** You decide whether to push the new entitlements to existing users immediately or keep them on their legacy configuration.
|
|
185
|
+
|
|
186
|
+
If you change your mind while editing, you can click **Discard** to delete the unpublished version and revert to the live state.
|
|
187
|
+
|
|
188
|
+
### Plan actions
|
|
189
|
+
|
|
190
|
+
Click the **⋯** menu next to the **Publish updates** button to access additional options.
|
|
191
|
+
|
|
192
|
+
| Action | Description |
|
|
193
|
+
|--------|-------------|
|
|
194
|
+
| **Edit** | Open the plan configuration to make changes |
|
|
195
|
+
| **Get Link** | Copy the direct checkout link for this plan |
|
|
196
|
+
| **Restrict by country** | Limit which countries can purchase this plan |
|
|
197
|
+
| **Archive** | Hide the plan from new customers while keeping it active for existing subscribers |
|
|
198
|
+
| **Restore last published version** | Discard unpublished changes and revert to the live version |
|
|
199
|
+
| **See last published version** | Preview what customers currently see on the live plan |
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Products"
|
|
3
|
+
slug: "product-catalog/products"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Create and manage your high-level product containers"
|
|
6
|
+
---
|
|
7
|
+
A product is the top-level container for what you sell. It groups together your pricing plans, features, and assets into a single family.
|
|
8
|
+
|
|
9
|
+
Before you can create plans or configure billing logic, you need to define the product they belong to.
|
|
10
|
+
|
|
11
|
+
<img height="200" src="/images/product-empty-screen.png" />
|
|
12
|
+
|
|
13
|
+
## Create a product
|
|
14
|
+
|
|
15
|
+
Follow these steps to set up a new product.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
Navigate to **Product Catalog > Products** in the sidebar.
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
Click **+ Create product** in the top right corner.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
<img height="200" src="/images/create-new-product.png" />
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
Fill out the basic information for your product.
|
|
35
|
+
|
|
36
|
+
* **Product name**
|
|
37
|
+
The public name shown to customers (e.g. "Pro Templates").
|
|
38
|
+
* **Identifier**
|
|
39
|
+
The unique ID used to reference this product in your API or SDK.
|
|
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).
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
Click **Create**. You will be redirected to the product details page.
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
<img height="200" src="/images/product-created.png" />
|
|
57
|
+
|
|
58
|
+
## Next steps
|
|
59
|
+
|
|
60
|
+
Now that you have a product container, you can define the pricing plans and deliverables inside it.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Subscriptions"
|
|
3
|
+
slug: "product-catalog/subscriptions"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Set up monthly or yearly billing for ongoing access"
|
|
6
|
+
---
|
|
7
|
+
Subscriptions are the default for traditional SaaS products. You charge customers on a regular schedule to maintain access to your application.
|
|
8
|
+
|
|
9
|
+
## Set up recurring billing
|
|
10
|
+
|
|
11
|
+
<img height="200" src="/images/subscription-pricing.png" />
|
|
12
|
+
|
|
13
|
+
1. Open your draft plan and ensure it is set to Paid
|
|
14
|
+
2. Under billing cycles select the intervals you want to offer like Monthly or Yearly
|
|
15
|
+
3. Enter the price for each interval
|
|
16
|
+
4. Click Save
|
|
17
|
+
|
|
18
|
+
You can enable multiple intervals on a single plan. When the customer lands on your checkout page they can toggle between paying monthly or paying upfront for the entire year.
|
|
19
|
+
|
|
20
|
+
## Subscription lifecycle
|
|
21
|
+
|
|
22
|
+
Kelviq handles the entire recurring payment lifecycle automatically. We manage
|
|
23
|
+
|
|
24
|
+
* Charging the card on file at the end of each billing cycle
|
|
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
|
|
28
|
+
|
|
29
|
+
You can skip building webhook listeners and just query the Kelviq SDK to check an active status when a user logs in. If your backend requires an event driven architecture we provide a complete webhooks system so you can listen and react to every subscription lifecycle event.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Tax settings"
|
|
3
|
+
slug: "product-catalog/tax-settings"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Configure price display rules and B2B exemptions"
|
|
6
|
+
---
|
|
7
|
+
You manage your tax configuration in two places. You set how prices display on individual plans and you set how business exemptions are handled globally.
|
|
8
|
+
|
|
9
|
+
## Plan tax behavior
|
|
10
|
+
|
|
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
|
+
|
|
13
|
+
<img height="400" src="/images/Tax-inclusive-drodown.png" />
|
|
14
|
+
|
|
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
|
+
|
|
17
|
+
<img height="400" src="/images/tax-modal.png" />
|
|
18
|
+
|
|
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
|
+
|
|
21
|
+
<img height="400" src="/images/select-countries-tax.png" />
|
|
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.
|
|
24
|
+
|
|
25
|
+
## Business tax ID behavior
|
|
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.
|
|
28
|
+
|
|
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
|
+
|
|
31
|
+
<img height="200" src="/images/tax-settings.png" />
|
|
32
|
+
|
|
33
|
+
Navigate to Settings in your sidebar and open the Tax settings page.
|
|
34
|
+
|
|
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
|
+
|
|
37
|
+
If you leave this disabled the checkout total remains the exact same and we attribute the extra margin directly to your account.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Usage based pricing"
|
|
3
|
+
slug: "product-catalog/usage-based-billing"
|
|
4
|
+
section: "product-catalog"
|
|
5
|
+
description: "Charge customers for the actual work your product performs"
|
|
6
|
+
---
|
|
7
|
+
AI products perform actual work. Flat rate subscriptions force you to guess at average compute costs which destroys your margins. Usage based pricing lets you charge for exact consumption.
|
|
8
|
+
|
|
9
|
+
## Set up a usage plan
|
|
10
|
+
|
|
11
|
+
To add consumption tracking to a plan open your pricing configuration and expand the usage pricing card.
|
|
12
|
+
|
|
13
|
+
<img height="200" src="/images/usage-pricing-card.png" />
|
|
14
|
+
|
|
15
|
+
### 1. Select or create a metered feature
|
|
16
|
+
|
|
17
|
+
Choose the specific metric you want to track from the dropdown list. You can select an existing feature like Platform API or Tokens consumed. To create a new metered feature just type a name like API request and hit enter.
|
|
18
|
+
|
|
19
|
+
<img height="200" src="/images/select-metered-feature.png" />
|
|
20
|
+
|
|
21
|
+
### 2. Choose your billing model
|
|
22
|
+
|
|
23
|
+
Select how payments are structured.
|
|
24
|
+
|
|
25
|
+
<img height="200" src="/images/select-billing-model.png" />
|
|
26
|
+
|
|
27
|
+
**Advance commitment**
|
|
28
|
+
Customers pay upfront for a baseline allotment of usage. This gives your users a predictable budget. They buy a set bucket of AI tokens or API requests at the start of the month. They consume what they paid for and avoid surprise overages.
|
|
29
|
+
|
|
30
|
+
**Pay as you go**
|
|
31
|
+
Customers pay in arrears based on exactly what they consumed. AI agents run autonomously and their usage fluctuates wildly. A user might trigger a research workflow that consumes massive amounts of compute overnight. Pay as you go ensures the agent keeps working without interruption while you capture the exact margin for the underlying infrastructure costs. We tally the final unit count at the end of the billing period and charge the card.
|
|
32
|
+
|
|
33
|
+
The pay as you go model only works on monthly plans.
|
|
34
|
+
|
|
35
|
+
### 3. Configure the pricing model
|
|
36
|
+
|
|
37
|
+
Kelviq supports five distinct ways to calculate the cost. Here is how the math works for each model.
|
|
38
|
+
|
|
39
|
+
<img height="400" src="/images/usage-pricing-models.png" />
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
#### Flat
|
|
44
|
+
|
|
45
|
+
Customers pay a fixed rate for each unit used. For example you charge \$0.10 per API call. A user makes 150 calls. The total is \$15.00.
|
|
46
|
+
|
|
47
|
+
<img height="400" src="/images/flat-pricing.png" />
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
#### Package
|
|
52
|
+
|
|
53
|
+
Customers buy usage units in predefined bundles. For example you charge \$5.00 for a package of 1000 AI tokens. A user consumes 2500 tokens which pushes them into a third package. The total is \$15.00.
|
|
54
|
+
|
|
55
|
+
<img height="400" src="/images/package-pricing.png" />
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
#### Tiered
|
|
60
|
+
|
|
61
|
+
Unit price decreases progressively as usage crosses defined thresholds. You fill the lower buckets first. For example units 1 to 100 cost \$1.00 each and units 101 to 200 cost \$0.50 each. A user consumes 150 units. The first 100 cost \$100 and the next 50 cost \$25. The total is \$125.
|
|
62
|
+
|
|
63
|
+
<img height="400" src="/images/tiered-pricing.png" />
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
#### Volume
|
|
68
|
+
|
|
69
|
+
All units are billed at the rate for the highest usage tier reached. Using the same thresholds as above a user consumes 150 units. Because they reached the second tier every single unit is priced at \$0.50. The total is \$75.
|
|
70
|
+
|
|
71
|
+
<img height="400" src="/images/volume-pricing.png" />
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
#### Stair-step
|
|
76
|
+
|
|
77
|
+
Customers pay a fixed price for the entire tier regardless of the exact unit count. For example usage between 1 and 100 units costs a flat \$10 and usage between 101 and 200 units costs a flat \$25. A user consumes 150 units. They pay exactly \$25.
|
|
78
|
+
|
|
79
|
+
<img height="400" src="/images/stair-step-pricing.png" />
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
### 4. Set the pricing rules
|
|
84
|
+
|
|
85
|
+
Once you pick a pricing model you define the exact boundaries.
|
|
86
|
+
|
|
87
|
+
If you select Tiered you specify the first unit and last unit for each bucket. You can charge a per unit price and a flat fee within that same tier.
|
|
88
|
+
|
|
89
|
+
When you configure prices across multiple intervals Kelviq can automatically prefill a 20 percent yearly discount for you to edit.
|
|
90
|
+
|
|
91
|
+
You can also set localized pricing for usage based billing. This lets you define different per unit rates for specific countries and currencies.
|
|
92
|
+
|
|
93
|
+
### 5. Set the usage reset cadence
|
|
94
|
+
|
|
95
|
+
Configure how often the usage meter clears out.
|
|
96
|
+
|
|
97
|
+
You can set the reset to Never for lifetime limits. You can also choose to reset it Every week or Every month.
|
|
98
|
+
|
|
99
|
+
For monthly resets you can align the timing perfectly by setting it to the first day of each month or tying it directly to the subscription start date.
|
|
100
|
+
|
|
101
|
+
### 6. Configure rollover and alerts
|
|
102
|
+
|
|
103
|
+
If your customers buy usage upfront you can let them keep what they do not use. Toggle Credit rollover to define how much carries over to the next billing cycle. You can set a specific percentage of unused units to roll over and apply a hard limit on the total units.
|
|
104
|
+
|
|
105
|
+
<img height="400" src="/images/credits-rollover.png" />
|
|
106
|
+
|
|
107
|
+
Keep your users informed as they consume their quota. Toggle Usage alerts and set your threshold type.
|
|
108
|
+
|
|
109
|
+
<img height="200" src="/images/usage-alerts.png" />
|
|
110
|
+
|
|
111
|
+
You can click Add threshold to stack multiple percentage alerts. For example you can notify them at 75 percent and again at 90 percent so they are never surprised by a cutoff or an unexpected bill.
|
|
112
|
+
|
|
113
|
+
To receive these alerts you must create a webhook for the feature.usage_alert event.
|
|
114
|
+
|
|
115
|
+
### 7. Stack multiple usage metrics
|
|
116
|
+
|
|
117
|
+
<img height="400" src="/images/stack-multiple-usage-metrics.png" />
|
|
118
|
+
|
|
119
|
+
AI products rarely track just one variable. You can add as many metered usage features as you want to a single plan. Just click the Add usage pricing button at the bottom of the section to set up another metric.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Create a promotion"
|
|
3
|
+
slug: "promotions/create-a-promotion"
|
|
4
|
+
section: "promotions"
|
|
5
|
+
description: "Set up purchasing power parity discounts, country overrides, and security enforcement"
|
|
6
|
+
---
|
|
7
|
+
A promotion ties a set of discounts to one or more of your products and plans. Once created, eligible visitors will see their local discount automatically.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
Go to **Promotions** in the sidebar, then click **+ Create promotion**.
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
Give the promotion a descriptive internal name (e.g. *PPP pricing* or *Black Friday*). This is not shown to customers.
|
|
17
|
+
|
|
18
|
+
The name field is required — you cannot create a promotion without one.
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
Choose which products and plans this promotion applies to. You can select multiple products, and for each product you can pick one or more plans.
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
Only **Published** plans appear in the selector. If a plan is missing, open the plan in **Product Catalog → Plans** and publish it first.
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
At least one plan must be selected before you can create the promotion.
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
Kelviq groups countries into economic tiers based on purchasing power. Enter a discount percentage for each group you want to target.
|
|
36
|
+
|
|
37
|
+
* Enter a value between 1–100 in the **Discount %** field for the relevant group.
|
|
38
|
+
* Leave the field empty (or set it to 0) for groups you do not want to discount.
|
|
39
|
+
|
|
40
|
+
You can see which countries belong to each group by expanding the group row.
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
To override the group discount for a specific country, use the **Country-specific discounts** section.
|
|
46
|
+
|
|
47
|
+
1. Search for the country by name.
|
|
48
|
+
2. Click the country to add it to the list.
|
|
49
|
+
3. Enter the exact discount percentage for that country.
|
|
50
|
+
|
|
51
|
+
Country overrides take precedence over the group discount. For example, if India is in a group with 30% off but you want to offer 40% for India specifically, add India as a country override with 40%.
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
Security toggles prevent abuse by blocking users who are masking or misrepresenting their location. All toggles are **enabled by default** — disable only if you have a specific reason to.
|
|
57
|
+
|
|
58
|
+
| Toggle | Description |
|
|
59
|
+
|--------|-------------|
|
|
60
|
+
| **VPN protection** | Block users connecting through a VPN |
|
|
61
|
+
| **Tor Browser protection** | Block anonymous traffic routed via Tor |
|
|
62
|
+
| **Proxy server protection** | Block known proxy IP addresses |
|
|
63
|
+
| **Apple Relay protection** | Block users using Apple Private Relay |
|
|
64
|
+
| **Strict country matching** | Require the billing address country to match the discount country |
|
|
65
|
+
| **Crawler protection** | Block bots from accessing localized pricing |
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
Click **Create promotion**. You will be taken to the promotion detail page where you can integrate the banner and customize its appearance.
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
## Editing a promotion
|
|
74
|
+
|
|
75
|
+
To update discounts, products, or security settings after creation, open the promotion and go to the **Edit rules** tab. Changes take effect immediately.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Customize the banner"
|
|
3
|
+
slug: "promotions/customize-banner"
|
|
4
|
+
section: "promotions"
|
|
5
|
+
description: "Adjust the appearance and behavior of the Promotions UI banner to match your brand"
|
|
6
|
+
---
|
|
7
|
+
Open a promotion and go to the **Customize banner** tab to control how the discount banner looks and behaves on your site.
|
|
8
|
+
|
|
9
|
+
## Appearance
|
|
10
|
+
|
|
11
|
+
* **Country message** — the text displayed to visitors. Use `{discount}` as a placeholder for the discount percentage and `{country}` for the visitor's country name.
|
|
12
|
+
Example: *"You qualify for a {discount}% discount in {country}."*
|
|
13
|
+
|
|
14
|
+
* **Background color** — the banner's background color. Accepts any hex value.
|
|
15
|
+
|
|
16
|
+
* **Background transparency** — opacity of the background, from 0 (fully transparent) to 100 (fully opaque).
|
|
17
|
+
|
|
18
|
+
* **Font color** — the main text color.
|
|
19
|
+
|
|
20
|
+
* **Highlight font color** — the color used for emphasized text (e.g. the discount percentage).
|
|
21
|
+
|
|
22
|
+
* **Font size** — text size in pixels.
|
|
23
|
+
|
|
24
|
+
* **Border radius** — corner rounding of the banner container, in pixels.
|
|
25
|
+
|
|
26
|
+
## Behavior
|
|
27
|
+
|
|
28
|
+
* **Placement** — choose whether the banner appears at the **top** or **bottom** of the viewport.
|
|
29
|
+
|
|
30
|
+
* **Close icon** — when enabled, a close button lets visitors dismiss the banner.
|
|
31
|
+
|
|
32
|
+
* **Unstyled mode** — when enabled, all styling controls are disabled and the banner renders without any Kelviq styles. Use this if you want to apply your own CSS from scratch.
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
Enabling unstyled mode will override all appearance settings above. You will need to style the banner entirely with your own CSS.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
## Save changes
|
|
40
|
+
|
|
41
|
+
Click **Update banner** to apply your changes. The banner updates in real time for new visitors.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Integrate the Promotions UI"
|
|
3
|
+
slug: "promotions/integrate"
|
|
4
|
+
section: "promotions"
|
|
5
|
+
description: "Add the Kelviq promotions banner to your app using HTML/JS, React, or the Direct API"
|
|
6
|
+
---
|
|
7
|
+
After creating a promotion, open it and go to the **Integration** tab. You will find ready-to-use code snippets for your stack — copy the snippet, paste in your `promotionId` and Client API key, and the banner will render automatically for eligible visitors.
|
|
8
|
+
|
|
9
|
+
You will need two values:
|
|
10
|
+
|
|
11
|
+
* **`promotionId`** — the unique ID of the promotion (pre-filled in the snippet).
|
|
12
|
+
* **`accessToken`** — your Client API key. Find it in **Settings → API keys → Client API key**.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## HTML / JS
|
|
17
|
+
|
|
18
|
+
Add the script snippet to the `<head>` of your page. It loads the SDK asynchronously, initializes it with your promotion, and renders the banner automatically. You can also call `getUpdatedPrice()`, `updatePriceElement()`, and `updatePrice()` to display discounted prices on the page.
|
|
19
|
+
|
|
20
|
+
Installation, `init()` options, auto price update with data attributes, JS API reference, and CSS hooks.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## React / Next.js
|
|
25
|
+
|
|
26
|
+
Install `@kelviq/react-promotions-ui`, wrap your app in `<KQProvider>`, and place `` where you want the banner to appear. Use `KQPriceFormatted` or the granular price components to show discounted prices anywhere on the page.
|
|
27
|
+
|
|
28
|
+
Installation, `KQProvider` props, `KQBanner`, `KQPriceFormatted`, granular price components, and sandbox setup.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Direct API
|
|
33
|
+
|
|
34
|
+
Fetch promotion data directly from the REST API if you want to apply discounts in a custom checkout flow or build your own UI. The response includes the active discount percentage for the caller's detected location.
|
|
35
|
+
|
|
36
|
+
The ready-to-use `curl` snippet is available in the **Integration** tab of your promotion.
|
|
37
|
+
|
|
38
|
+
Full API reference — request parameters, response schema, and example response.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Promotions"
|
|
3
|
+
slug: "promotions/overview"
|
|
4
|
+
section: "promotions"
|
|
5
|
+
description: "Boost global sales with purchasing power parity and country-specific discounts"
|
|
6
|
+
---
|
|
7
|
+
Promotions let you offer location-based discounts to customers around the world — automatically. Set up purchasing power parity (PPP) pricing, enforce security rules to prevent abuse, and render a customizable banner or discounted prices on your storefront — all from the Kelviq dashboard.
|
|
8
|
+
|
|
9
|
+
Setup takes less than 5 minutes and works with your existing product catalog.
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
Apply discount percentages to economic tier groups — countries with similar purchasing power are grouped automatically. Override any group with a country-specific discount when you need finer control.
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
Display the discounted price directly on your pricing page using the Promotions UI SDK. Supports formatted prices, granular price components, and original vs. discounted price comparison.
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
Block VPNs, proxies, Tor users, and crawlers from claiming localized discounts they're not entitled to. Enforced automatically at checkout.
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
Render a fully customizable banner on your site that shows customers their local discount. Available as an HTML snippet, React component, or via the API.
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
## How it works
|
|
32
|
+
|
|
33
|
+
1. **Create a promotion** — give it a name, pick which products and plans it applies to, and configure discounts.
|
|
34
|
+
2. **Integrate** — add the Kelviq SDK snippet or React component to your frontend. The banner renders automatically for eligible visitors.
|
|
35
|
+
3. **Customize** — adjust the banner's appearance (colors, font, placement, close icon) to match your brand.
|
|
36
|
+
|
|
37
|
+
## Next steps
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
Step-by-step guide to setting up PPP discounts, country overrides, and security rules.
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
Add the banner to your site using HTML/JS, React, or the Direct API.
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
Change colors, font, placement, and more to match your brand.
|