@kelviq/mcp-server 1.2.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/README.md +40 -3
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +1 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/ai/docs-for-agents.md +21 -0
  6. package/dist/docs/ai/overview.md +43 -0
  7. package/dist/docs/api-reference/authentication.md +9 -3
  8. package/dist/docs/api-reference/introduction.md +23 -2
  9. package/dist/docs/backend-integration/node-sdk.md +12 -6
  10. package/dist/docs/backend-integration/python-sdk.md +14 -8
  11. package/dist/docs/changelog.md +352 -3
  12. package/dist/docs/checkout/checkout-configuration.md +25 -75
  13. package/dist/docs/checkout/checkout-design.md +76 -0
  14. package/dist/docs/checkout/checkout-examples.md +212 -0
  15. package/dist/docs/checkout/checkout-metadata.md +1 -1
  16. package/dist/docs/checkout/custom-fields.md +60 -0
  17. package/dist/docs/checkout/embed-checkout.md +280 -0
  18. package/dist/docs/checkout/payment-methods/upi.md +69 -0
  19. package/dist/docs/checkout/payment-methods.md +119 -0
  20. package/dist/docs/checkout/static-checkout-url.md +3 -2
  21. package/dist/docs/cli/commands.md +57 -4
  22. package/dist/docs/cli/kelviq-config.md +1 -1
  23. package/dist/docs/cli/overview.md +1 -0
  24. package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
  25. package/dist/docs/customer-portal/overview.md +7 -7
  26. package/dist/docs/customer-portal/retention.md +109 -0
  27. package/dist/docs/customers-management/overview.md +105 -0
  28. package/dist/docs/frontend-integration/js-sdk.md +11 -11
  29. package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
  30. package/dist/docs/frontend-integration/react-sdk.md +8 -49
  31. package/dist/docs/frontend-integration/react-ui.md +8 -6
  32. package/dist/docs/getstarted/fees.md +27 -11
  33. package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
  34. package/dist/docs/getstarted/merchant-of-record.md +18 -24
  35. package/dist/docs/getstarted/overview.md +98 -0
  36. package/dist/docs/getstarted/review-process.md +59 -59
  37. package/dist/docs/guides/agent-toolkit.md +14 -9
  38. package/dist/docs/guides/mcp-server.md +24 -9
  39. package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
  40. package/dist/docs/guides/sandbox.md +6 -4
  41. package/dist/docs/guides/set-up-with-ai.md +43 -0
  42. package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
  43. package/dist/docs/guides/subscription-integration.md +1 -1
  44. package/dist/docs/guides/test-payments.md +640 -0
  45. package/dist/docs/guides/webhooks.md +182 -30
  46. package/dist/docs/integrations/woocommerce.md +88 -0
  47. package/dist/docs/integrations/zapier.md +22 -0
  48. package/dist/docs/legal/account-and-funds.md +59 -0
  49. package/dist/docs/legal/approved-prohibited-policy.md +32 -27
  50. package/dist/docs/legal/payment-flow-diagram.md +7 -7
  51. package/dist/docs/manifest.json +160 -41
  52. package/dist/docs/openapi.json +1359 -109
  53. package/dist/docs/payouts/overview.md +14 -12
  54. package/dist/docs/payouts/payout-account.md +1 -1
  55. package/dist/docs/payouts/transactions.md +3 -3
  56. package/dist/docs/product-catalog/create-a-feature.md +3 -3
  57. package/dist/docs/product-catalog/digital-downloads.md +5 -5
  58. package/dist/docs/product-catalog/discounts.md +2 -2
  59. package/dist/docs/product-catalog/entitlements.md +20 -27
  60. package/dist/docs/product-catalog/free-and-trials.md +4 -4
  61. package/dist/docs/product-catalog/license-keys.md +56 -29
  62. package/dist/docs/product-catalog/links.md +3 -3
  63. package/dist/docs/product-catalog/location-based-pricing.md +6 -10
  64. package/dist/docs/product-catalog/one-time-payments.md +3 -7
  65. package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
  66. package/dist/docs/product-catalog/plans.md +22 -19
  67. package/dist/docs/product-catalog/products.md +11 -3
  68. package/dist/docs/product-catalog/proration.md +69 -0
  69. package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
  70. package/dist/docs/product-catalog/subscriptions.md +52 -22
  71. package/dist/docs/product-catalog/tax-settings.md +8 -8
  72. package/dist/docs/product-catalog/usage-alerts.md +7 -7
  73. package/dist/docs/product-catalog/usage-based-billing.md +156 -29
  74. package/dist/docs/product-catalog/usage-limits.md +78 -0
  75. package/dist/docs/promotions/create-a-promotion.md +2 -2
  76. package/dist/docs/promotions/overview.md +1 -1
  77. package/dist/docs/quickstart/core-concepts.md +36 -30
  78. package/dist/docs/quickstart/dashboard-setup.md +26 -22
  79. package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
  80. package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
  81. package/dist/docs/sales/checkout-sessions.md +28 -39
  82. package/dist/docs/sales/orders.md +30 -54
  83. package/dist/docs/settings/customer-emails.md +52 -0
  84. package/dist/docs/settings/members.md +27 -0
  85. package/dist/docs/settings/profile.md +26 -0
  86. package/dist/docs/settings/zapier.md +22 -0
  87. package/dist/http/errors.d.ts +20 -1
  88. package/dist/http/errors.js +83 -31
  89. package/dist/http/errors.js.map +1 -1
  90. package/dist/schemas/kelviq.d.ts +54 -0
  91. package/dist/schemas/kelviq.js +64 -0
  92. package/dist/schemas/kelviq.js.map +1 -1
  93. package/dist/server.js +3 -2
  94. package/dist/server.js.map +1 -1
  95. package/dist/tools/imports.d.ts +68 -0
  96. package/dist/tools/imports.js +242 -0
  97. package/dist/tools/imports.js.map +1 -0
  98. package/dist/tools/index.d.ts +2 -1
  99. package/dist/tools/index.js +4 -1
  100. package/dist/tools/index.js.map +1 -1
  101. 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 kelviq into your app, you need to configure your **products, plans, and features** in the dashboard.
7
- This setup defines how your pricing and entitlements will work.
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 **Products → Create product**
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: **28 Days** (when enabled), **Monthly**, **Yearly**, **3 Months**, or **One Time**
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 based pricing
40
+ ### Usage-based pricing
41
+
42
+ To charge for consumption, such as compute or agent runs:
39
43
 
40
- To charger your users based on consumption like compute or agent runs you can add usage based pricing.
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
- 1. In the Price section select the usage billing option
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
- ### Regional pricing
51
+ ### Price localization
48
52
 
49
53
  To offer localized prices in different currencies:
50
54
 
51
- 1. In the Price section, click **Add Region** under Regional Pricing
52
- 2. Select a currency (e.g., Indian Rupee, Euro)
53
- 3. Enter prices for each billing cycle in that currency
54
- 4. Click **Add Currency**
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
- - **Switch (Boolean)** — on or off
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
- - **Metered** — tracked consumption, usage events sent to Kelviq, resets each billing cycle
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
- The last step is to publish your plan, so customers can see it and purchase it.
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 set up and synced with Stripe.
119
+ Your plan is now published and ready for customers.
116
120
  Next, you can integrate Kelviq into your app:
117
121
 
118
- - Use **checkout links** to let customers purchase your plans
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 **SDK** to check feature access and track usage
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://tidycal.com/neravath/15-minute-meeting).
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
- After setting up your product and plans in the dashboard, you can bring them into your app using the kelviq SDKs and UI components.
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
- > Note: In this guide we use the **Node SDK** and **React SDK** as examples.
9
- > Other SDKs like Python, JavaScript, are also available — the steps are the same.
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
- ## 1. Create a customer (optional)
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
- Typically, you create a customer record when someone signs up in your app.
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
- This is optional, but creating a customer in kelviq makes it easy to track subscriptions and usage in the dashboard.
24
+ ### Work in sandbox first
19
25
 
20
- ### Install the Node SDK
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
- // Create a customer on signup
35
- const newCustomer = await client.customers.create({
36
- customerId: "unique-customer-001",
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: "Node SDK User",
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 plan in Kelviq has a checkout link that you can use to send customers directly to checkout.
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. In the dashboard, go to your **Product → Plan**
51
- 2. Click **Get Link** in the top right
52
- 3. Copy the checkout URL
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
- You can use checkout links in multiple ways:
74
+ ### Attach the customer
57
75
 
58
- - **Direct link** — Share the URL in emails, landing pages, or marketing campaigns
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://checkout.kelviq.com/your-plan-id?customer_id=unique-customer-001">
64
- Buy Now
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
- When a customer completes checkout, their subscription and entitlements are automatically available in Kelviq.
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
- Once a customer completes a purchase, their entitlements are available in the SDK.
75
- You can check feature access in the frontend (React SDK) or backend (Node SDK).
76
- In all examples we’ll keep using the same customer ID: `unique-customer-001`.
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
- ### React: show or hide UI based on entitlements
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 '@kelviq/react-sdk';
144
+ import { ShowWhenBooleanEntitled } from "@kelviq/react-sdk";
82
145
 
83
146
  <ShowWhenBooleanEntitled
84
- featureId="enable-dark-mode"
147
+ featureId="priority-support"
85
148
  loadingComponent={<p>Checking…</p>}
86
- fallback={<p>Dark mode not available</p>}
149
+ fallback={<a href="/upgrade">Upgrade for priority support</a>}
87
150
  >
88
- <button>Toggle Dark Mode</button>
151
+
89
152
  </ShowWhenBooleanEntitled>
90
153
  ```
91
154
 
92
155
  ### React: read all entitlements
93
156
 
94
157
  ```tsx
95
- import { useAllEntitlements } from '@kelviq/react-sdk';
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 ? 'Enabled' : 'Disabled'} ({ent.featureType})
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
- ### Backend check with Node
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: "unique-customer-001",
117
- featureId: "max_upload_size_mb",
185
+ customerId: "cust_123",
186
+ featureId: "max-projects",
118
187
  });
119
188
 
120
- if (ent && file.sizeMB > (ent.usageLimit ?? Infinity)) {
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 (metered features)
200
+ ## 4. Report usage (Meter features)
128
201
 
129
- For metered features (like downloads, exports, AI generations, or API calls), send usage events from your backend.
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 '@kelviq/node-sdk';
205
+ import { BEHAVIOUR_CHOICES } from "@kelviq/node-sdk";
133
206
 
134
207
  await client.reporting.reportUsage({
135
- customerId: "unique-customer-001",
136
- featureId: "downloads",
208
+ customerId: "cust_123",
209
+ featureId: "ai-credits",
137
210
  value: 1,
138
- behaviour: BEHAVIOUR_CHOICES.DELTA, // or SET
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
- ## Need help?
219
+ ## Next steps
145
220
 
146
- Have questions, need help with implementation, or want a walkthrough?
147
- Email us at **hi@kelviq.com** or [book a demo](https://tidycal.com/neravath/15-minute-meeting).
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 &rarr; Notifications** to control the feature for your whole organization.
61
+ Use the **Abandoned cart recovery** toggle in **Settings &rarr; 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
- The reminder timing and email content are fixed. There is currently no option to change the schedule, resend a reminder manually, or exclude individual checkouts.
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 Sessions"
2
+ title: "Checkout sessions"
3
3
  slug: "sales/checkout-sessions"
4
4
  section: "sales"
5
- description: "Monitor live traffic and debug failed purchase attempts"
5
+ description: "Every checkout attempt, paid or not, with a timeline of what the customer did"
6
6
  ---
7
- While the **Orders** page tracks successful revenue, the **Checkout Sessions** page tracks every single attempt.
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
- This is your granular, real-time log of what is happening on your payment page right now. It is essential for debugging failed transactions and recovering abandoned carts.
9
+ Open **Sales → Checkout sessions**.
10
10
 
11
- ## Accessing sessions
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
- Go to **Sales > Checkout sessions** in the sidebar.
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
- Use the status tabs to isolate specific types of traffic:
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 on any session to see the raw data. This is useful if you need to understand *why* a transaction failed (e.g. "Card expired" vs "Insufficient funds").
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 height="200" src="/images/checkout-session-detail.png" alt="Detailed view of a checkout session including timeline" />
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
- ### Customer & context
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
- ### The timeline
42
- The timeline allows you to reconstruct the customer's journey step-by-step.
43
- 1. **Session created:** The moment they clicked your buy button.
44
- 2. **Details provided:** When they filled in their email or card info.
45
- 3. **Outcome:** The specific failure reason (e.g. `card_declined`) or success message.
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
- ## Actions & recovery
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
- This page gives you tools to assist customers who are stuck.
45
+ ## Custom field responses
50
46
 
51
- * **Recover sales**
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: "Track revenue and manage individual customer purchases"
5
+ description: "Every purchase made through your checkout, with its status, amount, and quick actions"
6
6
  ---
7
- The **Orders** page is your central hub for transaction history. It shows a real-time list of every purchase made through your checkout.
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
- Navigate to **Sales > Orders** in the sidebar to access it.
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
- <img height="200" src="/images/orders-list-view.png" alt="Orders list view showing customer email, product, and status" />
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
- ## The order list
13
+ ## Order statuses
14
14
 
15
- The main view provides a high-level summary of your incoming revenue. You can see:
16
- * **Customer:** Email address of the buyer.
17
- * **Product:** What they purchased.
18
- * **Status:** The current state (Paid, Refunded, Chargeback).
19
- * **Date:** When the order was placed.
20
- * **Revenue:** The total amount captured.
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
- ### Filtering
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
- ### Quick actions
28
- Click the **three-dot menu (...)** on any row to perform quick actions without opening the full details.
27
+ ## Quick actions
29
28
 
30
- <img height="200" src="/images/orders-quick-actions.png" alt="Meatball menu showing refund and receipt options" />
29
+ Click **⋯** at the end of a row:
31
30
 
32
- * **Refund payment:** Initiate a full or partial refund.
33
- * **Send receipt:** Resend the email receipt to the customer.
34
- * **Generate invoice:** Download the official invoice for the transaction.
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 **Order Drawer**. This panel gives you complete control over that specific transaction.
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
- * **Licenses:**
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
- ### Subscription
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
- ### Timeline
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
- <img height="200" src="/images/order-timeline.png" alt="Timeline view showing order creation, payment success, and email receipts" />
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
- * Order created
72
- * Receipts and invoices sent
73
- * Payment success or failure
74
- * Subscription creation
50
+ ## Custom field responses
75
51
 
76
- This is useful for debugging customer issues, such as verifying if they actually received their receipt email.
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).