@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.
- 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 +352 -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 +4 -4
- 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/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/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,12 +8,13 @@ capabilities at once:
|
|
|
8
8
|
|
|
9
9
|
1. **Typed tools** for the full Kelviq REST API — manage products, plans,
|
|
10
10
|
features, entitlements, customers, subscriptions, checkout sessions, license
|
|
11
|
-
keys, usage, promotions, and the customer portal
|
|
11
|
+
keys, usage, promotions, and the customer portal, and import an existing
|
|
12
|
+
store from Lemon Squeezy.
|
|
12
13
|
2. **Searchable documentation** — the entire Kelviq docs site is bundled
|
|
13
14
|
inside the package and exposed as MCP resources plus `docs_search` /
|
|
14
15
|
`docs_read` tools, so the LLM can ground its answers in the canonical docs.
|
|
15
16
|
|
|
16
|
-
> **
|
|
17
|
+
> **58 tools** across **13 domains**, plus a resource for every docs page and
|
|
17
18
|
> the full OpenAPI spec. Works offline for docs Q&A — only API tools require a
|
|
18
19
|
> key.
|
|
19
20
|
|
|
@@ -92,6 +93,7 @@ key). Docs tools (`docs_search`, `docs_read`) work with no keys at all.
|
|
|
92
93
|
| `KELVIQ_ENV` | no | `sandbox` | `sandbox` or `production`; switches both API hosts (base + edge). Any other value fails fast at startup. |
|
|
93
94
|
| `KELVIQ_BASE_URL` | no | per `KELVIQ_ENV` | Override (self-host, custom routing). Wins over `KELVIQ_ENV`. |
|
|
94
95
|
| `KELVIQ_EDGE_URL` | no | per `KELVIQ_ENV` | Override the edge host (entitlements + promotions). Wins over `KELVIQ_ENV`. |
|
|
96
|
+
| `LEMONSQUEEZY_API_KEY` | only for `import_start` from Lemon Squeezy | — | Lemon Squeezy API key for the store being imported. Read from the environment only: it is never a tool input, and it is hidden in tool results, in its JSON-escaped, URL-encoded and HTML-escaped forms too. A value shorter than 20 characters is refused before any request. |
|
|
95
97
|
|
|
96
98
|
> **Keys only work against their own environment** — the API enforces
|
|
97
99
|
> key↔host binding server-side, so a sandbox key against the production host
|
|
@@ -169,6 +171,41 @@ through the retrieve endpoints before anything is written.
|
|
|
169
171
|
- `plan_entitlements_list` / `plan_entitlements_add` (`feature` takes a UUID or identifier) / `plan_entitlement_update` / `plan_entitlement_delete`
|
|
170
172
|
- `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
|
|
171
173
|
|
|
174
|
+
### Imports
|
|
175
|
+
- `import_start` — queue a server-side import of a Lemon Squeezy store: profile, products and plans, customers, files, orders, renewals, discount codes and license keys
|
|
176
|
+
|
|
177
|
+
`dryRun` is a required input. A dry run goes through the whole import, saves
|
|
178
|
+
nothing and emails a report of what a real run would do, so the model is told
|
|
179
|
+
to run one for a store's first import and to start a real import only when the
|
|
180
|
+
user explicitly asks for it. The call returns as soon as the import is queued;
|
|
181
|
+
the report arrives by email and there is nothing to poll.
|
|
182
|
+
|
|
183
|
+
A real run publishes each imported plan, so it can be bought as soon as the
|
|
184
|
+
app points at it, and imported discount codes work at checkout. Pass
|
|
185
|
+
`publishPlan: false` to import plans as drafts, or `publishDiscount: false` to
|
|
186
|
+
leave the codes switched off. Running the import again adds only what is new.
|
|
187
|
+
It also publishes plans an earlier run left as drafts and switches on codes
|
|
188
|
+
that are still off, unless those inputs are `false`. Archived plans and plans
|
|
189
|
+
that already have a published version are left alone. A plan that could not be
|
|
190
|
+
published stays a draft and is named in the report's warnings. A code limited
|
|
191
|
+
to plans that are not published stays off, with a warning.
|
|
192
|
+
|
|
193
|
+
- The result is the API's response plus two fields: `environment` (`sandbox`
|
|
194
|
+
or `production`, the environment the import was queued in) and `note`, which
|
|
195
|
+
says that the import is queued and not finished, where the report will be
|
|
196
|
+
emailed, and that there is no status to check.
|
|
197
|
+
- The tool is annotated as destructive (`destructiveHint: true`), because a
|
|
198
|
+
real run publishes the imported plans by default and can overwrite the
|
|
199
|
+
business profile.
|
|
200
|
+
- `KELVIQ_SERVER_API_KEY` must be a server key created by the organization
|
|
201
|
+
owner. A key created by another team member is refused.
|
|
202
|
+
- The Lemon Squeezy key is read from `LEMONSQUEEZY_API_KEY`. There is no key
|
|
203
|
+
input, so it never passes through the conversation. When the key is missing
|
|
204
|
+
or rejected, the error tells the model to have it corrected in the server
|
|
205
|
+
environment, not to ask for it.
|
|
206
|
+
- Imported subscriptions are history. They keep billing on Lemon Squeezy, and
|
|
207
|
+
Kelviq does not charge them.
|
|
208
|
+
|
|
172
209
|
### Docs (no API key required)
|
|
173
210
|
- `docs_search` — full-text search across the bundled docs; returns slugs
|
|
174
211
|
- `docs_read` — fetch a single doc page by slug
|
|
@@ -205,7 +242,7 @@ npx -y @modelcontextprotocol/inspector \
|
|
|
205
242
|
npx -y @kelviq/mcp-server@latest
|
|
206
243
|
```
|
|
207
244
|
|
|
208
|
-
Opens a browser UI where you can browse all
|
|
245
|
+
Opens a browser UI where you can browse all 58 tools, fill in arguments, and
|
|
209
246
|
run them against the real Kelviq API. Pre-fill env vars by exporting them
|
|
210
247
|
before the command:
|
|
211
248
|
|
package/dist/config.d.ts
CHANGED
|
@@ -3,6 +3,11 @@ export type KelviqEnv = 'production' | 'sandbox';
|
|
|
3
3
|
export interface KelviqConfig {
|
|
4
4
|
serverApiKey: string | undefined;
|
|
5
5
|
clientApiKey: string | undefined;
|
|
6
|
+
/**
|
|
7
|
+
* Lemon Squeezy API key, used only by `import_start` to start a store import.
|
|
8
|
+
* Read from the environment so it never has to pass through a conversation.
|
|
9
|
+
*/
|
|
10
|
+
lemonSqueezyApiKey?: string | undefined;
|
|
6
11
|
baseUrl: string;
|
|
7
12
|
edgeUrl: string;
|
|
8
13
|
userAgent: string;
|
package/dist/config.js
CHANGED
|
@@ -41,6 +41,7 @@ export function loadConfig(env = process.env) {
|
|
|
41
41
|
return {
|
|
42
42
|
serverApiKey: read('KELVIQ_SERVER_API_KEY'),
|
|
43
43
|
clientApiKey: read('KELVIQ_CLIENT_API_KEY'),
|
|
44
|
+
lemonSqueezyApiKey: read('LEMONSQUEEZY_API_KEY'),
|
|
44
45
|
baseUrl: stripSlash(read('KELVIQ_BASE_URL') || defaultBaseUrl),
|
|
45
46
|
edgeUrl: stripSlash(edgeOverride),
|
|
46
47
|
userAgent: `kelviq-mcp/${getPackageVersion()} (+https://kelviq.com)`,
|
package/dist/config.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Docs for agents"
|
|
3
|
+
slug: "ai/docs-for-agents"
|
|
4
|
+
section: "ai"
|
|
5
|
+
description: "Give your coding agent the Kelviq docs through llms.txt or the docs MCP server"
|
|
6
|
+
---
|
|
7
|
+
Point your agent at the Kelviq docs so it answers from them instead of guessing.
|
|
8
|
+
|
|
9
|
+
| Resource | Use it for |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| [`llms.txt`](https://docs.kelviq.com/llms.txt) | An index of every docs page, in Markdown |
|
|
12
|
+
| [`llms-full.txt`](https://docs.kelviq.com/llms-full.txt) | All the docs in one file |
|
|
13
|
+
| `https://docs.kelviq.com/mcp` | Docs MCP server: search and read the docs from any MCP client |
|
|
14
|
+
|
|
15
|
+
In Claude Code, add the docs MCP server with:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
claude mcp add --transport http kelviq-docs https://docs.kelviq.com/mcp
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
In other MCP clients, add `https://docs.kelviq.com/mcp` as a remote HTTP server.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Kelviq and AI"
|
|
3
|
+
slug: "ai/overview"
|
|
4
|
+
section: "ai"
|
|
5
|
+
description: "Set up Kelviq with your coding agent, or connect your agent to Kelviq and its docs"
|
|
6
|
+
---
|
|
7
|
+
Kelviq works with the AI tools you already use. Your coding agent can create your plans, add checkout and feature checks to your app, and wire up webhooks. You review and approve each change.
|
|
8
|
+
|
|
9
|
+
## For humans
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
Copy a prompt from the dashboard and paste it into Claude Code, Cursor, Codex, Lovable, Replit, or Bolt.
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
Define products, features, and plans as code and sync them from the terminal.
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
The quickest start:
|
|
22
|
+
|
|
23
|
+
1. Open **Settings → Set up with AI** in the dashboard.
|
|
24
|
+
2. Copy the keys block into your project's `.env.local`.
|
|
25
|
+
3. Copy the prompt and paste it into your agent as the first message.
|
|
26
|
+
|
|
27
|
+
Start in sandbox, where your agent builds and tests with test cards. When it works, `kelviq promote` copies your catalog to production. Business verification and your keys stay with you.
|
|
28
|
+
|
|
29
|
+
## For agents
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
The MCP server plus skills that teach Claude Code how Kelviq works.
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
Manage customers, plans, subscriptions, and more from any MCP client.
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
`llms.txt` and a docs MCP server, so your agent answers from the Kelviq docs.
|
|
@@ -4,7 +4,7 @@ slug: "api-reference/authentication"
|
|
|
4
4
|
section: "api-reference"
|
|
5
5
|
description: "Authenticate securely with environment-scoped Kelviq API keys"
|
|
6
6
|
---
|
|
7
|
-
Kelviq API uses API keys to authenticate requests. All API requests must be made over HTTPS; calls made over plain HTTP will fail. API requests without authentication will also fail.
|
|
7
|
+
The Kelviq API uses API keys to authenticate requests. All API requests must be made over HTTPS; calls made over plain HTTP will fail. API requests without authentication will also fail.
|
|
8
8
|
|
|
9
9
|
## API Keys
|
|
10
10
|
|
|
@@ -32,14 +32,20 @@ You can get your API key from the Kelviq application dashboard.
|
|
|
32
32
|
|
|
33
33
|
1. Navigate to **Settings**.
|
|
34
34
|
2. Go to the [**API keys**](https://app.kelviq.com/settings/api-keys) section.
|
|
35
|
-
3. Copy
|
|
35
|
+
3. Copy the key appropriate for your integration:
|
|
36
|
+
- **Client API Key** for supported calls made from browsers or distributed applications.
|
|
37
|
+
- **Server API Key** for calls made from your trusted backend.
|
|
36
38
|
|
|
37
39
|
---
|
|
38
40
|
|
|
39
41
|
## Authorization
|
|
40
42
|
|
|
41
|
-
To authenticate your requests, pass
|
|
43
|
+
To authenticate your requests, pass the appropriate API key as a Bearer token in the `Authorization` header.
|
|
42
44
|
|
|
43
45
|
```bash
|
|
44
46
|
Authorization: Bearer YOUR_API_KEY
|
|
45
47
|
```
|
|
48
|
+
|
|
49
|
+
Most management APIs require a Server API Key. The License Activate, Validate, and Deactivate APIs accept either a Client API Key or a Server API Key, allowing license lifecycle calls from both customer-facing software and trusted backends. Check each endpoint's authentication note before using a Client API Key.
|
|
50
|
+
|
|
51
|
+
[Learn about license API authentication →](/product-catalog/license-keys#authentication)
|
|
@@ -42,7 +42,7 @@ curl https://sandboxapi.kelviq.com/api/v1/catalog/products/ \
|
|
|
42
42
|
--header "Accept: application/json"
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
Use a Client API Key for supported browser integrations. Never expose a Server API Key in client-side code.
|
|
45
|
+
Use a Client API Key for supported browser and distributed-app integrations. For example, the license activation, validation, and deactivation endpoints accept either a Client API Key or a Server API Key. Never expose a Server API Key in client-side code.
|
|
46
46
|
|
|
47
47
|
[Read the authentication guide →](/api-reference/authentication)
|
|
48
48
|
|
|
@@ -122,6 +122,27 @@ curl "https://sandboxapi.kelviq.com/api/v1/subscriptions/?customer_id=customer_1
|
|
|
122
122
|
|
|
123
123
|
Consult the endpoint reference before adding a query parameter; unsupported parameters may be ignored or rejected.
|
|
124
124
|
|
|
125
|
+
## Rate limits
|
|
126
|
+
|
|
127
|
+
To keep the API responsive for everyone, requests are rate limited per organization. The limit applies to all endpoints authenticated with a Server or Client API Key, and differs by environment:
|
|
128
|
+
|
|
129
|
+
| Environment | Limit |
|
|
130
|
+
| --- | --- |
|
|
131
|
+
| Production | `500 requests` / minute |
|
|
132
|
+
| Sandbox | `100 requests` / minute |
|
|
133
|
+
|
|
134
|
+
The limit applies to your whole organization, not to an individual API key — Server and Client API Key requests share the same quota. Sandbox and production are isolated environments, so each maintains its own limit.
|
|
135
|
+
|
|
136
|
+
If you exceed the limit, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"detail": "Request was throttled. Expected available in 42 seconds."
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Honor the `Retry-After` header and back off before retrying. If your integration regularly approaches the limit, batch or cache requests where possible rather than polling.
|
|
145
|
+
|
|
125
146
|
## Error handling
|
|
126
147
|
|
|
127
148
|
The API uses standard HTTP status codes and returns detailed error information in the response body.
|
|
@@ -136,7 +157,7 @@ The API uses standard HTTP status codes and returns detailed error information i
|
|
|
136
157
|
| `409` | Conflict | The request conflicts with an existing resource, such as a duplicate account. |
|
|
137
158
|
| `422` | Unprocessable Entity | The request is well-formed but contains invalid or unsupported values. |
|
|
138
159
|
| `428` | Precondition Required | A required account configuration, such as billing-provider authentication, is incomplete. |
|
|
139
|
-
| `429` | Too Many Requests | The
|
|
160
|
+
| `429` | Too Many Requests | The [rate limit](#rate-limits) has been exceeded. |
|
|
140
161
|
| `500` | Internal Server Error | Kelviq could not complete the request because of an unexpected server error. |
|
|
141
162
|
| `502` | Bad Gateway | Kelviq received an invalid response from an upstream service. |
|
|
142
163
|
| `503` | Service Unavailable | The service is temporarily unavailable. |
|
|
@@ -74,6 +74,12 @@ const client = new Kelviq({
|
|
|
74
74
|
|
|
75
75
|
Set `enableCache: false` to disable caching.
|
|
76
76
|
|
|
77
|
+
To drop a customer's cached entitlements before the window expires, for example in a `subscription.paused`, `subscription.resumed`, or `subscription.cancelled` webhook handler:
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
await client.entitlements.invalidateCache({ customerId });
|
|
81
|
+
```
|
|
82
|
+
|
|
77
83
|
### Share the cache across instances
|
|
78
84
|
|
|
79
85
|
The in-memory cache and offline reporting queue belong to one Node process and disappear when it restarts. Use the optional Redis store when multiple processes or containers need one shared, durable cache and queue.
|
|
@@ -981,8 +987,8 @@ const page = await client.refunds.list({
|
|
|
981
987
|
|
|
982
988
|
* `search` : Search by refund ID, order ID, customer name, email, or ID.
|
|
983
989
|
* `status` : Filter by refund status. One of `"PENDING"`, `"PROCESSING"`, `"SUCCEEDED"`, `"FAILED"`, `"CANCELED"`.
|
|
984
|
-
* `startDate` : Include refunds created on or after this date (`YYYY-MM-DD`).
|
|
985
|
-
* `endDate` : Include refunds created on or before this date (`YYYY-MM-DD`).
|
|
990
|
+
* `startDate` : Include refunds created on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with an offset (`2026-07-01T00:00:00+05:30`) for an exact instant.
|
|
991
|
+
* `endDate` : Include refunds created on or before this date. A date (`YYYY-MM-DD`) is inclusive of the whole UTC day; a datetime is an exclusive upper bound, so pass the next local midnight (`2026-07-02T00:00:00+05:30`) to get exactly one local day.
|
|
986
992
|
* `page` : Page number to return.
|
|
987
993
|
* `pageSize` : Number of results per page. Defaults to 10, maximum 100.
|
|
988
994
|
|
|
@@ -1155,8 +1161,8 @@ console.log(page.results[0].amountTotal, page.results[0].morFeeBreakdown);
|
|
|
1155
1161
|
|
|
1156
1162
|
* `search` : Search by payment-provider IDs, customer name, email or ID, product name, or payment method type.
|
|
1157
1163
|
* `status` : Filter by transaction status. One of `"success"`, `"failure"`, `"pending"`.
|
|
1158
|
-
* `startDate` : Include transactions created on or after this date (`YYYY-MM-DD`).
|
|
1159
|
-
* `endDate` : Include transactions created on or before this date (`YYYY-MM-DD`).
|
|
1164
|
+
* `startDate` : Include transactions created on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with an offset (`2026-07-01T00:00:00+05:30`) for an exact instant.
|
|
1165
|
+
* `endDate` : Include transactions created on or before this date. A date (`YYYY-MM-DD`) is inclusive of the whole UTC day; a datetime is an exclusive upper bound, so pass the next local midnight (`2026-07-02T00:00:00+05:30`) to get exactly one local day.
|
|
1160
1166
|
* `page` : Page number to return.
|
|
1161
1167
|
* `pageSize` : Number of results per page. Defaults to 10, maximum 100.
|
|
1162
1168
|
|
|
@@ -1416,7 +1422,7 @@ res.redirect(portalLink);
|
|
|
1416
1422
|
{
|
|
1417
1423
|
"token": "cpt-4f7c5dc4-da9f-447b-d447-6206d835ed6d:23fca530-ajeb-4685-b3d5-9918h6d38275",
|
|
1418
1424
|
"email": "geo@example.com",
|
|
1419
|
-
"customerPortalUrl": "https://www.kelviq.com/portal/
|
|
1425
|
+
"customerPortalUrl": "https://www.kelviq.com/portal/acme/"
|
|
1420
1426
|
}
|
|
1421
1427
|
```
|
|
1422
1428
|
|
|
@@ -1541,7 +1547,7 @@ See [Webhook event types](/guides/webhooks#event-types) for the complete list of
|
|
|
1541
1547
|
|
|
1542
1548
|
### Best practices
|
|
1543
1549
|
|
|
1544
|
-
* **Return quickly** — respond with a `2xx` status before doing any heavy processing. Kelviq retries up to 3 times at 60-second intervals
|
|
1550
|
+
* **Return quickly** — respond with a `2xx` status before doing any heavy processing. Kelviq waits 10 seconds for a response. It retries up to 3 times at 60-second intervals on a timeout, connection failure, `5xx` or `429`; other non-`2xx` responses are not retried.
|
|
1545
1551
|
* **Use idempotency** — use the `webhook-id` header (or the event `id` field) to detect and skip duplicate deliveries.
|
|
1546
1552
|
* **Validate every request** — always verify the signature before trusting the payload.
|
|
1547
1553
|
|
|
@@ -76,6 +76,12 @@ client = Kelviq.create_sync_client(
|
|
|
76
76
|
|
|
77
77
|
Set `enable_cache=False` to disable caching.
|
|
78
78
|
|
|
79
|
+
To drop a customer's cached entitlements before the window expires, for example in a `subscription.paused`, `subscription.resumed`, or `subscription.cancelled` webhook handler:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
client.entitlements.invalidate_cache(customerId=customer_id)
|
|
83
|
+
```
|
|
84
|
+
|
|
79
85
|
### Share the cache across workers
|
|
80
86
|
|
|
81
87
|
The in-memory cache and offline reporting queue belong to one process and disappear when it restarts. Use the optional Redis store when multiple workers, processes, or containers need one shared, durable cache and queue.
|
|
@@ -364,11 +370,11 @@ print(f"Checkout Session URL: {response.checkoutUrl}")
|
|
|
364
370
|
|
|
365
371
|
* `offeringId` (str): The ID (uuid) of the offering the customer is checking out with.
|
|
366
372
|
|
|
367
|
-
* `pricingTableId` (str):
|
|
373
|
+
* `pricingTableId` (str): The id (uuid) of the pricingTable being used for this checkout. (Considered only if `offeringId` is not provided)
|
|
368
374
|
|
|
369
|
-
* `ruleId` (str):
|
|
375
|
+
* `ruleId` (str): The id (uuid) of the pricing rule being applied. (Considered only if `offeringId` is not provided)
|
|
370
376
|
|
|
371
|
-
* `customerId` (str):
|
|
377
|
+
* `customerId` (str): The ID of the customer initiating the checkout. If you omit it, Kelviq creates a new customer.
|
|
372
378
|
|
|
373
379
|
* `features` (List[Dict[str, Union[str, int]]]): Optional. A list of dictionaries, where each dictionary represents a feature and its desired quantity. Each dictionary **must** have two keys:
|
|
374
380
|
* `"identifier"` (str): The unique identifier for the feature.
|
|
@@ -1167,8 +1173,8 @@ page = await async_client.refunds.list(status="SUCCEEDED", page=1, page_size=10)
|
|
|
1167
1173
|
|
|
1168
1174
|
* `search` : Search by refund ID, order ID, customer name, email, or ID.
|
|
1169
1175
|
* `status` : Filter by refund status. One of `"PENDING"`, `"PROCESSING"`, `"SUCCEEDED"`, `"FAILED"`, `"CANCELED"`.
|
|
1170
|
-
* `start_date` : Include refunds created on or after this date (`YYYY-MM-DD`).
|
|
1171
|
-
* `end_date` : Include refunds created on or before this date (`YYYY-MM-DD`).
|
|
1176
|
+
* `start_date` : Include refunds created on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with an offset (`2026-07-01T00:00:00+05:30`) for an exact instant.
|
|
1177
|
+
* `end_date` : Include refunds created on or before this date. A date (`YYYY-MM-DD`) is inclusive of the whole UTC day; a datetime is an exclusive upper bound, so pass the next local midnight (`2026-07-02T00:00:00+05:30`) to get exactly one local day.
|
|
1172
1178
|
* `page` : Page number to return.
|
|
1173
1179
|
* `page_size` : Number of results per page. Defaults to 10, maximum 100.
|
|
1174
1180
|
|
|
@@ -1371,8 +1377,8 @@ page = await async_client.transactions.list(status="success")
|
|
|
1371
1377
|
|
|
1372
1378
|
* `search` : Search by payment-provider IDs, customer name, email or ID, product name, or payment method type.
|
|
1373
1379
|
* `status` : Filter by transaction status. One of `"success"`, `"failure"`, `"pending"`.
|
|
1374
|
-
* `start_date` : Include transactions created on or after this date (`YYYY-MM-DD`).
|
|
1375
|
-
* `end_date` : Include transactions created on or before this date (`YYYY-MM-DD`).
|
|
1380
|
+
* `start_date` : Include transactions created on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with an offset (`2026-07-01T00:00:00+05:30`) for an exact instant.
|
|
1381
|
+
* `end_date` : Include transactions created on or before this date. A date (`YYYY-MM-DD`) is inclusive of the whole UTC day; a datetime is an exclusive upper bound, so pass the next local midnight (`2026-07-02T00:00:00+05:30`) to get exactly one local day.
|
|
1376
1382
|
* `page` : Page number to return.
|
|
1377
1383
|
* `page_size` : Number of results per page. Defaults to 10, maximum 100.
|
|
1378
1384
|
|
|
@@ -1778,7 +1784,7 @@ See [Webhook event types](/guides/webhooks#event-types) for the complete list of
|
|
|
1778
1784
|
|
|
1779
1785
|
### Best practices
|
|
1780
1786
|
|
|
1781
|
-
* **Return quickly** — respond with a `2xx` status before doing any heavy processing. Kelviq retries up to 3 times at 60-second intervals
|
|
1787
|
+
* **Return quickly** — respond with a `2xx` status before doing any heavy processing. Kelviq waits 10 seconds for a response. It retries up to 3 times at 60-second intervals on a timeout, connection failure, `5xx` or `429`; other non-`2xx` responses are not retried.
|
|
1782
1788
|
* **Use idempotency** — use the `webhook-id` header (or the event `id` field) to detect and skip duplicate deliveries.
|
|
1783
1789
|
* **Validate every request** — always verify the signature before trusting the payload.
|
|
1784
1790
|
|