@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.
Files changed (111) 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 +369 -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 +5 -5
  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/_resolve.js +14 -10
  96. package/dist/tools/_resolve.js.map +1 -1
  97. package/dist/tools/features.js +9 -2
  98. package/dist/tools/features.js.map +1 -1
  99. package/dist/tools/imports.d.ts +68 -0
  100. package/dist/tools/imports.js +242 -0
  101. package/dist/tools/imports.js.map +1 -0
  102. package/dist/tools/index.d.ts +2 -1
  103. package/dist/tools/index.js +4 -1
  104. package/dist/tools/index.js.map +1 -1
  105. package/dist/tools/product-files.js +10 -3
  106. package/dist/tools/product-files.js.map +1 -1
  107. package/dist/tools/product-settings.js +10 -3
  108. package/dist/tools/product-settings.js.map +1 -1
  109. package/dist/tools/products.js +14 -4
  110. package/dist/tools/products.js.map +1 -1
  111. 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
- > **57 tools** across **12 domains**, plus a resource for every docs page and
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 57 tools, fill in arguments, and
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)`,
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
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 your **Server API Key** to use in your application.
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 your **Server API Key** as a Bearer token in the `Authorization` header.
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 request rate limit has been exceeded. |
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/paritydeals/"
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 if it does not receive a `2xx`.
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): Required. The id (uuid) of the pricingTable being used for this checkout. (Considered only if `offeringId` is not provided)
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): Required. The id (uuid) of the pricing rule being applied. (Considered only if `offeringId` is not provided)
375
+ * `ruleId` (str): The id (uuid) of the pricing rule being applied. (Considered only if `offeringId` is not provided)
370
376
 
371
- * `customerId` (str): Required. The ID of the customer initiating the checkout. (If not provided, a new customer will be created)
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 if it does not receive a `2xx`.
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