@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.
- package/README.md +40 -3
- package/dist/config.d.ts +5 -0
- package/dist/config.js +1 -0
- package/dist/config.js.map +1 -1
- package/dist/docs/ai/docs-for-agents.md +21 -0
- package/dist/docs/ai/overview.md +43 -0
- package/dist/docs/api-reference/authentication.md +9 -3
- package/dist/docs/api-reference/introduction.md +23 -2
- package/dist/docs/backend-integration/node-sdk.md +12 -6
- package/dist/docs/backend-integration/python-sdk.md +14 -8
- package/dist/docs/changelog.md +369 -3
- package/dist/docs/checkout/checkout-configuration.md +25 -75
- package/dist/docs/checkout/checkout-design.md +76 -0
- package/dist/docs/checkout/checkout-examples.md +212 -0
- package/dist/docs/checkout/checkout-metadata.md +1 -1
- package/dist/docs/checkout/custom-fields.md +60 -0
- package/dist/docs/checkout/embed-checkout.md +280 -0
- package/dist/docs/checkout/payment-methods/upi.md +69 -0
- package/dist/docs/checkout/payment-methods.md +119 -0
- package/dist/docs/checkout/static-checkout-url.md +3 -2
- package/dist/docs/cli/commands.md +57 -4
- package/dist/docs/cli/kelviq-config.md +1 -1
- package/dist/docs/cli/overview.md +1 -0
- package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
- package/dist/docs/customer-portal/overview.md +7 -7
- package/dist/docs/customer-portal/retention.md +109 -0
- package/dist/docs/customers-management/overview.md +105 -0
- package/dist/docs/frontend-integration/js-sdk.md +11 -11
- package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
- package/dist/docs/frontend-integration/react-sdk.md +8 -49
- package/dist/docs/frontend-integration/react-ui.md +8 -6
- package/dist/docs/getstarted/fees.md +27 -11
- package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
- package/dist/docs/getstarted/merchant-of-record.md +18 -24
- package/dist/docs/getstarted/overview.md +98 -0
- package/dist/docs/getstarted/review-process.md +59 -59
- package/dist/docs/guides/agent-toolkit.md +14 -9
- package/dist/docs/guides/mcp-server.md +24 -9
- package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
- package/dist/docs/guides/sandbox.md +6 -4
- package/dist/docs/guides/set-up-with-ai.md +43 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
- package/dist/docs/guides/subscription-integration.md +1 -1
- package/dist/docs/guides/test-payments.md +640 -0
- package/dist/docs/guides/webhooks.md +182 -30
- package/dist/docs/integrations/woocommerce.md +88 -0
- package/dist/docs/integrations/zapier.md +22 -0
- package/dist/docs/legal/account-and-funds.md +59 -0
- package/dist/docs/legal/approved-prohibited-policy.md +32 -27
- package/dist/docs/legal/payment-flow-diagram.md +7 -7
- package/dist/docs/manifest.json +160 -41
- package/dist/docs/openapi.json +1359 -109
- package/dist/docs/payouts/overview.md +14 -12
- package/dist/docs/payouts/payout-account.md +1 -1
- package/dist/docs/payouts/transactions.md +3 -3
- package/dist/docs/product-catalog/create-a-feature.md +3 -3
- package/dist/docs/product-catalog/digital-downloads.md +5 -5
- package/dist/docs/product-catalog/discounts.md +2 -2
- package/dist/docs/product-catalog/entitlements.md +20 -27
- package/dist/docs/product-catalog/free-and-trials.md +5 -5
- package/dist/docs/product-catalog/license-keys.md +56 -29
- package/dist/docs/product-catalog/links.md +3 -3
- package/dist/docs/product-catalog/location-based-pricing.md +6 -10
- package/dist/docs/product-catalog/one-time-payments.md +3 -7
- package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
- package/dist/docs/product-catalog/plans.md +22 -19
- package/dist/docs/product-catalog/products.md +11 -3
- package/dist/docs/product-catalog/proration.md +69 -0
- package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
- package/dist/docs/product-catalog/subscriptions.md +52 -22
- package/dist/docs/product-catalog/tax-settings.md +8 -8
- package/dist/docs/product-catalog/usage-alerts.md +7 -7
- package/dist/docs/product-catalog/usage-based-billing.md +156 -29
- package/dist/docs/product-catalog/usage-limits.md +78 -0
- package/dist/docs/promotions/create-a-promotion.md +2 -2
- package/dist/docs/promotions/overview.md +1 -1
- package/dist/docs/quickstart/core-concepts.md +36 -30
- package/dist/docs/quickstart/dashboard-setup.md +26 -22
- package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
- package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
- package/dist/docs/sales/checkout-sessions.md +28 -39
- package/dist/docs/sales/orders.md +30 -54
- package/dist/docs/settings/customer-emails.md +52 -0
- package/dist/docs/settings/members.md +27 -0
- package/dist/docs/settings/profile.md +26 -0
- package/dist/docs/settings/zapier.md +22 -0
- package/dist/http/errors.d.ts +20 -1
- package/dist/http/errors.js +83 -31
- package/dist/http/errors.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +54 -0
- package/dist/schemas/kelviq.js +64 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +3 -2
- package/dist/server.js.map +1 -1
- package/dist/tools/_resolve.js +14 -10
- package/dist/tools/_resolve.js.map +1 -1
- package/dist/tools/features.js +9 -2
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/imports.d.ts +68 -0
- package/dist/tools/imports.js +242 -0
- package/dist/tools/imports.js.map +1 -0
- package/dist/tools/index.d.ts +2 -1
- package/dist/tools/index.js +4 -1
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/product-files.js +10 -3
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +10 -3
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +14 -4
- package/dist/tools/products.js.map +1 -1
- package/package.json +1 -1
|
@@ -3,14 +3,16 @@ title: "Dashboard setup"
|
|
|
3
3
|
slug: "quickstart/dashboard-setup"
|
|
4
4
|
section: "quickstart"
|
|
5
5
|
---
|
|
6
|
-
Before you can integrate
|
|
7
|
-
This
|
|
6
|
+
Before you can integrate Kelviq into your app, you need to configure your **products, plans, and features** in the dashboard.
|
|
7
|
+
This defines your pricing and what each plan includes.
|
|
8
|
+
|
|
9
|
+
Using Claude Code, Cursor, or another coding agent? [Set up with AI](/guides/set-up-with-ai) gives you a prompt that creates your products, plans, and features for you. You approve each change.
|
|
8
10
|
|
|
9
11
|
---
|
|
10
12
|
|
|
11
13
|
## Create a product
|
|
12
14
|
|
|
13
|
-
1. In the sidebar, go to **
|
|
15
|
+
1. In the sidebar, go to **Product catalog → Products** and click **Create product**
|
|
14
16
|
2. Enter a product name (e.g., "Design Course", "Pro Plan", "Premium Templates")
|
|
15
17
|
3. Click **Save** — you'll be redirected to the product page
|
|
16
18
|
|
|
@@ -30,28 +32,30 @@ From the product page:
|
|
|
30
32
|
|
|
31
33
|
From the plan page, click the **Price** section to configure pricing:
|
|
32
34
|
|
|
33
|
-
1. Select billing cycles: **
|
|
35
|
+
1. Select billing cycles: **Monthly**, **3 Months**, **6 Months**, **Yearly**, **28 Days** (when enabled), or **One Time**
|
|
34
36
|
2. Enter prices for each selected billing cycle
|
|
35
37
|
3. (Optional) Enable **Free trial** and set the trial period in days
|
|
36
38
|
4. Click **Save**
|
|
37
39
|
|
|
38
|
-
### Usage
|
|
40
|
+
### Usage-based pricing
|
|
41
|
+
|
|
42
|
+
To charge for consumption, such as compute or agent runs:
|
|
39
43
|
|
|
40
|
-
|
|
44
|
+
1. In the Price section, add a usage charge
|
|
45
|
+
2. Pick the Meter feature to bill, such as AI tokens or workflow executions
|
|
46
|
+
3. Set the price per unit
|
|
47
|
+
4. Keep a flat base price too if you want hybrid pricing
|
|
41
48
|
|
|
42
|
-
|
|
43
|
-
2. Choose the specific feature you want to track like AI tokens or workflow executions
|
|
44
|
-
3. Set your price per unit
|
|
45
|
-
4. Combine this with a flat base fee if you want a hybrid pricing model
|
|
49
|
+
See [Usage-based pricing](/product-catalog/usage-based-billing).
|
|
46
50
|
|
|
47
|
-
###
|
|
51
|
+
### Price localization
|
|
48
52
|
|
|
49
53
|
To offer localized prices in different currencies:
|
|
50
54
|
|
|
51
|
-
1. In the
|
|
52
|
-
2.
|
|
53
|
-
3. Enter
|
|
54
|
-
4. Click **
|
|
55
|
+
1. In the price editor, expand **Price localization**
|
|
56
|
+
2. Under **Choose a currency**, select a currency (e.g., Indian Rupee, Euro) and click **Add localized price**
|
|
57
|
+
3. Enter the price for each billing cycle in that currency, then click **Save** in that currency's panel
|
|
58
|
+
4. Click **Save** at the bottom of the price editor
|
|
55
59
|
|
|
56
60
|
This allows you to set specific prices for different markets rather than relying on automatic currency conversion.
|
|
57
61
|
|
|
@@ -91,13 +95,13 @@ Click the **Features & limits** section to configure feature access and usage qu
|
|
|
91
95
|
|
|
92
96
|
Features are created independently and can be attached to multiple plans with different values:
|
|
93
97
|
|
|
94
|
-
- **
|
|
98
|
+
- **Boolean** — on or off
|
|
95
99
|
Examples: priority support, bonus content access, community access, custom branding
|
|
96
100
|
|
|
97
101
|
- **Customizable** — a fixed numeric limit, no usage reporting
|
|
98
102
|
Examples: number of downloads, max projects, storage limit (10 GB, 100 GB)
|
|
99
103
|
|
|
100
|
-
- **
|
|
104
|
+
- **Meter feature** — tracked consumption, usage events sent to Kelviq, resets each billing cycle
|
|
101
105
|
Examples: API calls, AI generations, video renders, exports per month
|
|
102
106
|
|
|
103
107
|
Once added, features appear in the plan's feature list. You can reorder or remove them as needed.
|
|
@@ -106,24 +110,24 @@ Once added, features appear in the plan's feature list. You can reorder or remov
|
|
|
106
110
|
|
|
107
111
|
## Publish the plan
|
|
108
112
|
|
|
109
|
-
|
|
113
|
+
Click **Publish** on the plan page. Plans stay drafts until you publish them, and customers can only buy published plans.
|
|
110
114
|
|
|
111
115
|
---
|
|
112
116
|
|
|
113
117
|
## Next steps
|
|
114
118
|
|
|
115
|
-
Your plan is now
|
|
119
|
+
Your plan is now published and ready for customers.
|
|
116
120
|
Next, you can integrate Kelviq into your app:
|
|
117
121
|
|
|
118
|
-
- Use
|
|
122
|
+
- Use [checkout links](/checkout/static-checkout-url) to let customers buy your plans
|
|
119
123
|
- Create a customer in Kelviq when a user signs up in your app
|
|
120
|
-
- Use the Kelviq
|
|
124
|
+
- Use the Kelviq [SDKs](/quickstart/integrate-with-your-app) to check feature access and track usage
|
|
121
125
|
|
|
122
126
|
---
|
|
123
127
|
|
|
124
128
|
## Need help?
|
|
125
129
|
|
|
126
130
|
Have questions, need help with implementation, or want a walkthrough?
|
|
127
|
-
Email us at **hi@kelviq.com** or [book a demo](https://
|
|
131
|
+
Email us at **hi@kelviq.com** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
|
|
128
132
|
|
|
129
133
|
---
|
|
@@ -3,105 +3,170 @@ title: "Integrate with your app"
|
|
|
3
3
|
slug: "quickstart/integrate-with-your-app"
|
|
4
4
|
section: "quickstart"
|
|
5
5
|
---
|
|
6
|
-
|
|
6
|
+
Your product and plans are published. This page connects them to your app: customers buy through a checkout link, and your app checks what each customer is entitled to.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
8
|
+
The page continues the **Acme AI** example from [Core concepts](/quickstart/core-concepts): a Pro plan with the identifier `pro`, and three features, `priority-support` (Boolean), `max-projects` (Customizable), and `ai-credits` (Meter).
|
|
9
|
+
|
|
10
|
+
Only selling through links, with no app code? You need just [Checkout links](#2-checkout-links). Everything else on this page is for apps that check feature access or track usage.
|
|
11
|
+
|
|
12
|
+
Code samples use the [Node SDK](/backend-integration/node-sdk) on the server and the [React SDK](/frontend-integration/react-sdk) in the browser. The [Python SDK](/backend-integration/python-sdk) has the same server methods, and the [JavaScript SDK](/frontend-integration/js-sdk) covers browsers without React.
|
|
10
13
|
|
|
11
14
|
---
|
|
12
15
|
|
|
13
|
-
##
|
|
16
|
+
## Before you start
|
|
17
|
+
|
|
18
|
+
### Get your API keys
|
|
19
|
+
|
|
20
|
+
Open **Settings → API keys**. The **server key** goes in your backend and must never ship to a browser. The **client key** goes in your frontend and only reads data.
|
|
14
21
|
|
|
15
|
-
|
|
16
|
-
When they complete a purchase, Kelviq maps the transaction to the customer record automatically.
|
|
22
|
+
<img src="/images/api-keys.webp" alt="API keys page in Settings showing the server and client keys" />
|
|
17
23
|
|
|
18
|
-
|
|
24
|
+
### Work in sandbox first
|
|
19
25
|
|
|
20
|
-
|
|
26
|
+
New accounts start in sandbox, where you can complete the whole flow with test cards. Sandbox and production keep separate keys, customers, and checkout links, so keep everything on this page in one environment:
|
|
27
|
+
|
|
28
|
+
- Tell each SDK which environment to use: `environment: 'sandbox'` on the Node client, `environment="sandbox"` on the React provider.
|
|
29
|
+
- Copy checkout links from the dashboard while in sandbox mode. Sandbox links include `/sandbox/` in the path.
|
|
30
|
+
|
|
31
|
+
When you are ready to take live payments, switch the dashboard to production and repeat the steps with production keys and links.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 1. Create a customer
|
|
36
|
+
|
|
37
|
+
Create a customer in Kelviq when someone signs up in your app, using your own user ID as the `customerId`. Every later call, from checkout to entitlement checks to usage reports, uses this same ID.
|
|
21
38
|
|
|
22
39
|
```bash
|
|
23
40
|
npm install @kelviq/node-sdk
|
|
24
|
-
|
|
41
|
+
```
|
|
25
42
|
|
|
26
43
|
```ts
|
|
27
44
|
import { Kelviq } from "@kelviq/node-sdk";
|
|
28
45
|
|
|
29
|
-
// API keys are under Settings → API keys in the dashboard
|
|
30
46
|
const client = new Kelviq({
|
|
31
47
|
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
|
|
48
|
+
environment: "sandbox", // omit in production
|
|
32
49
|
});
|
|
33
50
|
|
|
34
|
-
//
|
|
35
|
-
|
|
36
|
-
customerId: "
|
|
51
|
+
// On signup
|
|
52
|
+
await client.customers.create({
|
|
53
|
+
customerId: "cust_123", // your app's user ID
|
|
37
54
|
email: "customer@example.com",
|
|
38
|
-
name: "
|
|
55
|
+
name: "Ada Lovelace",
|
|
39
56
|
});
|
|
40
57
|
```
|
|
41
58
|
|
|
59
|
+
If you skip this step, Kelviq creates a customer at checkout with its own ID. That is fine for link-only selling, but your app then has no ID to check entitlements with.
|
|
60
|
+
|
|
42
61
|
---
|
|
43
62
|
|
|
44
63
|
## 2. Checkout links
|
|
45
64
|
|
|
46
|
-
Every
|
|
65
|
+
Every published product has a checkout link. You can use it as is, or add query parameters to choose the plan and attach a customer.
|
|
47
66
|
|
|
48
67
|
### Get a checkout link
|
|
49
68
|
|
|
50
|
-
1.
|
|
51
|
-
2. Click **Get Link**
|
|
52
|
-
3.
|
|
53
|
-
|
|
54
|
-
### Using checkout links
|
|
69
|
+
1. Go to **Product catalog → Products** and open your product
|
|
70
|
+
2. Click **Get Link** to open the link builder
|
|
71
|
+
3. Choose the plans to include and the default billing period
|
|
72
|
+
4. Copy the generated URL
|
|
55
73
|
|
|
56
|
-
|
|
74
|
+
### Attach the customer
|
|
57
75
|
|
|
58
|
-
|
|
59
|
-
- **Button on your site** — Link your "Buy Now" or "Get Access" buttons to the checkout URL
|
|
60
|
-
- **With customer ID** — Append `?customer_id=unique-customer-001` to link the purchase to an existing customer
|
|
76
|
+
A checkout link on its own does not know who is buying. To tie the purchase to the customer from step 1, add `customer_id` to the link. Use `?` before the first parameter and `&` before each one after it.
|
|
61
77
|
|
|
62
78
|
```html
|
|
63
|
-
<a href="https://
|
|
64
|
-
|
|
79
|
+
<a href="https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/?plan_identifier=pro&customer_id=cust_123">
|
|
80
|
+
Upgrade to Pro
|
|
65
81
|
</a>
|
|
66
82
|
```
|
|
67
83
|
|
|
68
|
-
|
|
84
|
+
Without `customer_id`, the link still works for emails, landing pages, and marketing campaigns. See [Static checkout URL](/checkout/static-checkout-url) for every parameter, including `success_url` for the page to return to after payment.
|
|
85
|
+
|
|
86
|
+
### Or create the checkout from your backend
|
|
87
|
+
|
|
88
|
+
When the customer is already logged in to your app, you can build the checkout on the server instead of in a link. The session carries the customer ID and the return URL, and nothing has to be assembled in the browser.
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import { CHARGE_PERIOD_CHOICES } from "@kelviq/node-sdk";
|
|
92
|
+
|
|
93
|
+
const { checkoutUrl } = await client.checkout.createSession({
|
|
94
|
+
planIdentifier: "pro",
|
|
95
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
96
|
+
customerId: "cust_123",
|
|
97
|
+
successUrl: "https://example.com/upgrade/success",
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
// Redirect the customer to checkoutUrl
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### After the purchase
|
|
104
|
+
|
|
105
|
+
When checkout completes, Kelviq creates the subscription and the customer's entitlements are live right away. Your app can read them with the checks in the next step. If you also want the event in your own systems, such as sending a welcome email, subscribe to `checkout.completed` and `subscription.created` through [webhooks](/guides/webhooks). Webhooks are optional.
|
|
106
|
+
|
|
107
|
+
A visit to `success_url` is not proof of payment. Check an entitlement or wait for the webhook before granting access.
|
|
69
108
|
|
|
70
109
|
---
|
|
71
110
|
|
|
72
111
|
## 3. Check feature access
|
|
73
112
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
113
|
+
Your app checks features, not plans. Moving `priority-support` to a different plan is a dashboard change, not a deploy.
|
|
114
|
+
|
|
115
|
+
### React: set up the provider
|
|
77
116
|
|
|
78
|
-
|
|
117
|
+
Wrap your app in `KelviqProvider` with the client key and the signed-in user's customer ID. Every hook and component below reads from it.
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
npm install @kelviq/react-sdk
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
```tsx
|
|
124
|
+
import { KelviqProvider } from "@kelviq/react-sdk";
|
|
125
|
+
|
|
126
|
+
function App() {
|
|
127
|
+
return (
|
|
128
|
+
<KelviqProvider
|
|
129
|
+
accessToken={process.env.NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY!}
|
|
130
|
+
customerId="cust_123"
|
|
131
|
+
environment="sandbox" // omit in production
|
|
132
|
+
>
|
|
133
|
+
|
|
134
|
+
</KelviqProvider>
|
|
135
|
+
);
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
See [`KelviqProvider`](/frontend-integration/react-sdk#kelviqprovider) for the full list of props.
|
|
140
|
+
|
|
141
|
+
### React: show or hide UI
|
|
79
142
|
|
|
80
143
|
```tsx
|
|
81
|
-
import { ShowWhenBooleanEntitled } from
|
|
144
|
+
import { ShowWhenBooleanEntitled } from "@kelviq/react-sdk";
|
|
82
145
|
|
|
83
146
|
<ShowWhenBooleanEntitled
|
|
84
|
-
featureId="
|
|
147
|
+
featureId="priority-support"
|
|
85
148
|
loadingComponent={<p>Checking…</p>}
|
|
86
|
-
fallback={<
|
|
149
|
+
fallback={<a href="/upgrade">Upgrade for priority support</a>}
|
|
87
150
|
>
|
|
88
|
-
|
|
151
|
+
|
|
89
152
|
</ShowWhenBooleanEntitled>
|
|
90
153
|
```
|
|
91
154
|
|
|
92
155
|
### React: read all entitlements
|
|
93
156
|
|
|
94
157
|
```tsx
|
|
95
|
-
import { useAllEntitlements } from
|
|
158
|
+
import { useAllEntitlements } from "@kelviq/react-sdk";
|
|
96
159
|
|
|
97
160
|
function EntitlementsList() {
|
|
98
|
-
const { data: entitlements } = useAllEntitlements();
|
|
161
|
+
const { data: entitlements, isLoading } = useAllEntitlements();
|
|
162
|
+
|
|
163
|
+
if (isLoading) return <p>Loading…</p>;
|
|
99
164
|
|
|
100
165
|
return (
|
|
101
166
|
<ul>
|
|
102
|
-
{Object.values(entitlements).map(ent => (
|
|
167
|
+
{Object.values(entitlements ?? {}).map((ent) => (
|
|
103
168
|
<li key={ent.featureId}>
|
|
104
|
-
{ent.featureId}: {ent.hasAccess ?
|
|
169
|
+
{ent.featureId}: {ent.hasAccess ? "Enabled" : "Disabled"} ({ent.featureType})
|
|
105
170
|
</li>
|
|
106
171
|
))}
|
|
107
172
|
</ul>
|
|
@@ -109,41 +174,57 @@ function EntitlementsList() {
|
|
|
109
174
|
}
|
|
110
175
|
```
|
|
111
176
|
|
|
112
|
-
|
|
177
|
+
The provider fetches entitlements once when it mounts. When the customer returns from checkout, call `refreshAllEntitlements` from the `useKelviq` hook so the new plan shows without a reload.
|
|
178
|
+
|
|
179
|
+
### Node: enforce a limit on the server
|
|
180
|
+
|
|
181
|
+
Anything that must not be bypassed belongs on the server. `max-projects` is a Customizable feature: each plan stores its own limit in `usageLimit`. `getEntitlement` returns `null` when the customer does not have the feature, so treat that as no access.
|
|
113
182
|
|
|
114
183
|
```ts
|
|
115
184
|
const ent = await client.entitlements.getEntitlement({
|
|
116
|
-
customerId: "
|
|
117
|
-
featureId: "
|
|
185
|
+
customerId: "cust_123",
|
|
186
|
+
featureId: "max-projects",
|
|
118
187
|
});
|
|
119
188
|
|
|
120
|
-
|
|
189
|
+
const maxProjects = ent?.hasAccess ? ent.usageLimit ?? Infinity : 0;
|
|
190
|
+
|
|
191
|
+
if (currentProjectCount >= maxProjects) {
|
|
121
192
|
throw new Error("Upgrade required");
|
|
122
193
|
}
|
|
123
194
|
```
|
|
124
195
|
|
|
196
|
+
The Node SDK caches entitlements for 60 seconds, so a plan change can take up to a minute to show on the server. Lower `cacheTtlMs` or set `enableCache: false` on the client if you need it sooner.
|
|
197
|
+
|
|
125
198
|
---
|
|
126
199
|
|
|
127
|
-
## 4. Report usage (
|
|
200
|
+
## 4. Report usage (Meter features)
|
|
128
201
|
|
|
129
|
-
For
|
|
202
|
+
For Meter features such as `ai-credits`, send usage events from your backend each time the customer consumes something. Kelviq counts them against the plan's limit and resets the count each billing cycle.
|
|
130
203
|
|
|
131
204
|
```ts
|
|
132
|
-
import { BEHAVIOUR_CHOICES } from
|
|
205
|
+
import { BEHAVIOUR_CHOICES } from "@kelviq/node-sdk";
|
|
133
206
|
|
|
134
207
|
await client.reporting.reportUsage({
|
|
135
|
-
customerId: "
|
|
136
|
-
featureId: "
|
|
208
|
+
customerId: "cust_123",
|
|
209
|
+
featureId: "ai-credits",
|
|
137
210
|
value: 1,
|
|
138
|
-
behaviour: BEHAVIOUR_CHOICES.DELTA,
|
|
211
|
+
behaviour: BEHAVIOUR_CHOICES.DELTA,
|
|
139
212
|
});
|
|
140
213
|
```
|
|
141
214
|
|
|
215
|
+
`DELTA` adds `value` to the customer's current usage. `SET` replaces current usage with `value`, for numbers you already count yourself, such as seats in use.
|
|
216
|
+
|
|
142
217
|
---
|
|
143
218
|
|
|
144
|
-
##
|
|
219
|
+
## Next steps
|
|
145
220
|
|
|
146
|
-
|
|
147
|
-
|
|
221
|
+
- [Pricing table and paywall components](/frontend-integration/react-ui) for a drop-in pricing page
|
|
222
|
+
- [Customer portal](/customer-portal/overview) so customers can manage their own subscription
|
|
223
|
+
- [Webhooks](/guides/webhooks) for events in your own systems
|
|
148
224
|
|
|
149
225
|
---
|
|
226
|
+
|
|
227
|
+
## Need help?
|
|
228
|
+
|
|
229
|
+
Have questions, need help with implementation, or want a walkthrough?
|
|
230
|
+
Email us at **hi@kelviq.com** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
|
|
@@ -6,7 +6,7 @@ description: "Automatically remind customers who start checkout but do not pay"
|
|
|
6
6
|
---
|
|
7
7
|
Abandoned cart recovery emails customers who start a checkout but do not complete payment. Kelviq detects the abandoned checkout, sends up to three reminder emails over three days, and expires the checkout after four. You do not need to build anything: detection, scheduling, and deduplication are handled for you.
|
|
8
8
|
|
|
9
|
-
The feature is on by default for every organization. You can turn it off in **Settings**.
|
|
9
|
+
The feature is on by default for every organization. You can turn it off in **Settings → Customer emails**.
|
|
10
10
|
|
|
11
11
|
## How a checkout becomes abandoned
|
|
12
12
|
|
|
@@ -52,13 +52,17 @@ Four days after creation, an unpaid checkout expires:
|
|
|
52
52
|
|
|
53
53
|
Completed, closed, or expired checkouts never receive reminders.
|
|
54
54
|
|
|
55
|
+
## Offer a discount in the final reminder
|
|
56
|
+
|
|
57
|
+
Turn on **Offer a discount in the final reminder** in **Settings → Customer emails** and enter a percentage. The final reminder then offers that much off the checkout total. Only one discount can be active per product, so the offer isn't sent if another discount already applies to the checkout.
|
|
58
|
+
|
|
55
59
|
## Turning it off and on
|
|
56
60
|
|
|
57
|
-
Use the **Abandoned cart recovery** toggle in **Settings →
|
|
61
|
+
Use the **Abandoned cart recovery** toggle in **Settings → Customer emails** to control the feature for your whole organization.
|
|
58
62
|
|
|
59
63
|
* Turning it off stops future reminder emails. Emails that were already sent cannot be recalled.
|
|
60
64
|
* Turning it back on resumes eligible reminders for checkouts that have not yet expired.
|
|
61
65
|
|
|
62
|
-
|
|
66
|
+
Kelviq runs the reminder schedule and writes the emails. You choose whether reminders go out and the discount in the final reminder.
|
|
63
67
|
|
|
64
68
|
To watch recovery in action, open [Checkout sessions](/sales/checkout-sessions). An abandoned checkout stays in its `open` or `processing` state until the customer returns and pays or the session expires.
|
|
@@ -1,58 +1,47 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "Checkout
|
|
2
|
+
title: "Checkout sessions"
|
|
3
3
|
slug: "sales/checkout-sessions"
|
|
4
4
|
section: "sales"
|
|
5
|
-
description: "
|
|
5
|
+
description: "Every checkout attempt, paid or not, with a timeline of what the customer did"
|
|
6
6
|
---
|
|
7
|
-
|
|
7
|
+
A checkout session is created each time a customer opens a checkout link or your app creates a checkout through the API. [Orders](/sales/orders) only show purchases that went through. Checkout sessions show every attempt, so you can see where customers stop.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Open **Sales → Checkout sessions**.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
<img src="/images/checkout-sessions/checkout-sessions-list.webp" alt="The Checkout sessions page with the status filter open, listing sessions with their amount, status, customer, product, and date" />
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Each row shows the session ID, the amount and billing period, the status, the customer's country and email (or N/A if they never entered one), the product and plan, and when the session was created. Search by name or session ID, filter by status, and change the date range above the list.
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
15
|
+
## Session statuses
|
|
17
16
|
|
|
18
|
-
|
|
17
|
+
| Status | What it means |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| **Open** | The customer has the checkout and hasn't paid yet. |
|
|
20
|
+
| **Processing** | The customer submitted a payment and it's being confirmed. |
|
|
21
|
+
| **Success** | The payment went through and an [order](/sales/orders) was created. |
|
|
22
|
+
| **Closed** | The session ended without a payment before it expired. |
|
|
23
|
+
| **Expired** | Nobody paid within four days of the session being created. |
|
|
19
24
|
|
|
20
|
-
|
|
21
|
-
* **Open:** Customers currently on the payment page.
|
|
22
|
-
* **Succeeded:** Completed purchases.
|
|
23
|
-
* **Failed:** Declined cards or errors.
|
|
24
|
-
* **Expired:** Sessions where the customer left without paying.
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
<img height="200" src="/images/checkout-sessions-list.png" alt="List of checkout sessions showing status and customer emails" />
|
|
25
|
+
A session that's still **Open** or **Processing** an hour after it was created, with no customer activity in the last 30 minutes, is treated as abandoned and gets [recovery emails](/sales/abandoned-cart-recovery) if the customer entered an email address.
|
|
28
26
|
|
|
29
27
|
## Session details
|
|
30
28
|
|
|
31
|
-
Click
|
|
29
|
+
Click a session to open its details: the items in the checkout, the customer, the payment method used, and the session timeline.
|
|
32
30
|
|
|
33
|
-
<img
|
|
31
|
+
<img src="/images/checkout-sessions/checkout-session-detail.webp" alt="Details of an expired checkout session, showing the purchased item and a timeline from Checkout started to Checkout session expired" />
|
|
34
32
|
|
|
35
|
-
|
|
36
|
-
See exactly who is attempting to buy and where they are coming from.
|
|
37
|
-
* **Customer info:** Email address, location, and IP address.
|
|
38
|
-
* **Product:** The specific item or license they are trying to purchase.
|
|
39
|
-
* **Device:** The payment method and device type used.
|
|
33
|
+
The timeline lists what happened in the session, newest first, with the time of each event. For example:
|
|
40
34
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
35
|
+
| Event | When it's added |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| **Checkout started** | The customer opened the checkout. Shows whether it's a subscription or one-time purchase, and the amount. |
|
|
38
|
+
| **Plan selected** | The customer picked a plan or billing period. Shows the plan, period, and price. |
|
|
39
|
+
| **Billing address updated** | The customer entered or changed their country or address. |
|
|
40
|
+
| **Checkout session abandoned** | The customer left without paying. |
|
|
41
|
+
| **Checkout session expired** | The session reached its four-day limit without a payment. |
|
|
46
42
|
|
|
47
|
-
|
|
43
|
+
Payment attempts appear in the timeline too, including the decline reason when a payment fails, such as `insufficient_funds`. Use it to answer "why didn't this customer get charged?" without asking them to try again.
|
|
48
44
|
|
|
49
|
-
|
|
45
|
+
## Custom field responses
|
|
50
46
|
|
|
51
|
-
|
|
52
|
-
If you see a **Failed** session, you can use the email address to reach out and offer support.
|
|
53
|
-
* **Share portal access**
|
|
54
|
-
For successful sessions, you can copy the **Portal Link** directly from the details view and send it to the customer manually.
|
|
55
|
-
* **Resend receipt**
|
|
56
|
-
Trigger a new email receipt if the customer missed the first one.
|
|
57
|
-
* **View order**
|
|
58
|
-
Click the **Order** button to jump straight to the official revenue record in the Orders page.
|
|
47
|
+
If the checkout collected [custom fields](/checkout/custom-fields), the customer's answers are saved on the session as `customFieldsData` in the API, and sent as `custom_fields_data` in the `checkout.completed` [webhook](/guides/webhooks#custom-field-responses).
|
|
@@ -2,75 +2,51 @@
|
|
|
2
2
|
title: "Orders"
|
|
3
3
|
slug: "sales/orders"
|
|
4
4
|
section: "sales"
|
|
5
|
-
description: "
|
|
5
|
+
description: "Every purchase made through your checkout, with its status, amount, and quick actions"
|
|
6
6
|
---
|
|
7
|
-
|
|
7
|
+
An order is created for each purchase made through your checkout: one-time payments, the first payment of a subscription, and each renewal. Open **Sales → Orders** to see them.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
<img src="/images/orders/orders-list.webp" alt="The Orders page with the status filter open, listing orders with their customer, product, status, date, and amount" />
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Each row shows the order ID, the customer's email and name, the product, the status, when the order was paid, and the amount. Search by name or order ID, filter by status, and change the date range with the filters above the list.
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Order statuses
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
15
|
+
| Status | What it means |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| **Pending payment** | The order was created and the payment hasn't completed yet. |
|
|
18
|
+
| **Complete** | The payment succeeded. Shown as **Completed** in the list. |
|
|
19
|
+
| **Failed** | The payment was attempted and declined, or it errored. No money was collected. |
|
|
20
|
+
| **Refunded** | The full amount was refunded to the customer. |
|
|
21
|
+
| **Partial refund** | Part of the amount was refunded. The rest stays with you. |
|
|
22
|
+
| **Canceled** | The payment was canceled before it completed. Nothing was charged. |
|
|
23
|
+
| **Fraudulent** | The payment was identified as fraudulent. |
|
|
21
24
|
|
|
22
|
-
|
|
23
|
-
You can filter the list to find specific transactions.
|
|
24
|
-
* **Date range:** Select specific days or months.
|
|
25
|
-
* **Status:** Filter by Paid, Refunded, or Chargeback.
|
|
25
|
+
The same values come back as `status` from the [Orders API](/api-reference/orders/list-orders): `PENDING`, `COMPLETE`, `FAILED`, `REFUNDED`, `PARTIAL_REFUND`, `CANCELLED`, and `FRAUDULENT`.
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
Click the **three-dot menu (...)** on any row to perform quick actions without opening the full details.
|
|
27
|
+
## Quick actions
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
Click **⋯** at the end of a row:
|
|
31
30
|
|
|
32
|
-
* **Refund payment:**
|
|
33
|
-
* **
|
|
34
|
-
* **Generate invoice:**
|
|
35
|
-
|
|
36
|
-
---
|
|
31
|
+
* **Refund payment:** refund the full amount or part of it.
|
|
32
|
+
* **Resend receipt:** email the receipt to the customer again.
|
|
33
|
+
* **Generate invoice:** create and download the invoice for the order.
|
|
37
34
|
|
|
38
35
|
## Order details
|
|
39
36
|
|
|
40
|
-
Click on any row to open the
|
|
41
|
-
|
|
42
|
-
<img height="200" src="/images/order-drawer-overview.png" alt="Side drawer showing customer details and order summary" />
|
|
43
|
-
|
|
44
|
-
### Overview
|
|
45
|
-
The default view shows the core transaction data.
|
|
46
|
-
* **Customer details:** Name, email, and IP address.
|
|
47
|
-
* **Payment info:** Credit card last-4, banking details, and billing address.
|
|
48
|
-
* **Order summary:** Line items, taxes (VAT/GST), discounts applied, and the total charge.
|
|
49
|
-
|
|
50
|
-
### Deliverables
|
|
51
|
-
Manage exactly what this specific customer received.
|
|
37
|
+
Click the customer on any row to open the order's details.
|
|
52
38
|
|
|
53
|
-
|
|
54
|
-
View the generated license key. You can edit activation limits, change the expiry date, or deactivate the key entirely if you suspect abuse.
|
|
55
|
-
* **Downloads:**
|
|
56
|
-
See which files the customer has access to. You can remove or hide specific files for this order if you need to revoke access to a particular asset.
|
|
57
|
-
* **Links:**
|
|
58
|
-
View the external links shared with this customer.
|
|
39
|
+
<img width="560" src="/images/orders/order-details.webp" alt="Order details for a $49 Acme Analytics Pro order, with the customer, line items, totals, and the order timeline" />
|
|
59
40
|
|
|
60
|
-
|
|
61
|
-
If the order is tied to a recurring plan, a **Subscription** tab will appear.
|
|
62
|
-
* Click the subscription ID to see the full billing history.
|
|
63
|
-
* Check upcoming renewal dates and past invoices.
|
|
64
|
-
* See if other products were bundled in the same plan.
|
|
41
|
+
The panel shows the order status and date, the customer's name, email, and country, and each item with its subtotal, discount, tax, and total. Click **⋯** at the top for the same actions as the list, plus **Copy signed portal link** to send the customer a link to their [customer portal](/customer-portal/overview).
|
|
65
42
|
|
|
66
|
-
|
|
67
|
-
The timeline acts as an audit log for the order. It tracks every event chronologically.
|
|
43
|
+
The tabs below the totals show what the customer received and what happened to the order:
|
|
68
44
|
|
|
69
|
-
|
|
45
|
+
* **Downloads:** the files the customer can download. You can remove or hide a file for this order to revoke access.
|
|
46
|
+
* **License:** the license key issued for the order. You can edit the activation limit, change the expiry date, or deactivate the key.
|
|
47
|
+
* **Links:** the links shared with the customer after purchase.
|
|
48
|
+
* **Timeline:** every event on the order, newest first, such as **Order created**, **Order completed**, receipts and invoices sent, and payment results. Use it to check, for example, whether a customer was sent their receipt.
|
|
70
49
|
|
|
71
|
-
|
|
72
|
-
* Receipts and invoices sent
|
|
73
|
-
* Payment success or failure
|
|
74
|
-
* Subscription creation
|
|
50
|
+
## Custom field responses
|
|
75
51
|
|
|
76
|
-
|
|
52
|
+
If the checkout collected [custom fields](/checkout/custom-fields), the customer's answers are saved on the order. You can see them in the order details drawer. They're returned as `customFieldsData` on the order in the API and as `custom_fields_data` in the `order.created`, `order.updated`, and `order.refunded` [webhooks](/guides/webhooks#custom-field-responses).
|