@kelviq/mcp-server 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +322 -0
  3. package/dist/config.d.ts +16 -0
  4. package/dist/config.js +45 -0
  5. package/dist/config.js.map +1 -0
  6. package/dist/docs/README.md +128 -0
  7. package/dist/docs/api-reference/authentication.md +41 -0
  8. package/dist/docs/backend-integration/node-sdk.md +1040 -0
  9. package/dist/docs/backend-integration/python-sdk.md +1198 -0
  10. package/dist/docs/changelog/app.md +80 -0
  11. package/dist/docs/changelog/checkout-api.md +59 -0
  12. package/dist/docs/changelog/js-promotions-ui.md +14 -0
  13. package/dist/docs/changelog/js-sdk.md +281 -0
  14. package/dist/docs/changelog/node-sdk.md +378 -0
  15. package/dist/docs/changelog/python-sdk.md +456 -0
  16. package/dist/docs/changelog/react-sdk.md +580 -0
  17. package/dist/docs/checkout/checkout-configuration.md +434 -0
  18. package/dist/docs/coustomers-management/overview.md +111 -0
  19. package/dist/docs/customer-portal/overview.md +81 -0
  20. package/dist/docs/frontend-integration/js-sdk.md +676 -0
  21. package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
  22. package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
  23. package/dist/docs/frontend-integration/react-sdk.md +1187 -0
  24. package/dist/docs/frontend-integration/react-ui.md +771 -0
  25. package/dist/docs/getstarted/fees.md +160 -0
  26. package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
  27. package/dist/docs/getstarted/merchant-of-record.md +64 -0
  28. package/dist/docs/getstarted/review-process.md +190 -0
  29. package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
  30. package/dist/docs/guides/subscription-integration.md +291 -0
  31. package/dist/docs/guides/webhooks.md +963 -0
  32. package/dist/docs/legal/approved-prohibited-policy.md +252 -0
  33. package/dist/docs/legal/buyer-terms.md +177 -0
  34. package/dist/docs/legal/compliant-user-flow.md +216 -0
  35. package/dist/docs/legal/master-service-agreement.md +404 -0
  36. package/dist/docs/legal/payment-flow-diagram.md +188 -0
  37. package/dist/docs/legal/seller-terms.md +169 -0
  38. package/dist/docs/manifest.json +415 -0
  39. package/dist/docs/monetization/offerings.md +156 -0
  40. package/dist/docs/monetization/pricing-tables.md +226 -0
  41. package/dist/docs/monetization/targeting-rules.md +278 -0
  42. package/dist/docs/openapi.json +5479 -0
  43. package/dist/docs/payouts/overview.md +43 -0
  44. package/dist/docs/payouts/payout-account.md +12 -0
  45. package/dist/docs/payouts/transactions.md +23 -0
  46. package/dist/docs/product-catalog/digital-downloads.md +117 -0
  47. package/dist/docs/product-catalog/discounts.md +69 -0
  48. package/dist/docs/product-catalog/entitlements.md +428 -0
  49. package/dist/docs/product-catalog/free-and-trials.md +36 -0
  50. package/dist/docs/product-catalog/license-keys.md +324 -0
  51. package/dist/docs/product-catalog/links.md +92 -0
  52. package/dist/docs/product-catalog/location-based-pricing.md +41 -0
  53. package/dist/docs/product-catalog/one-time-payments.md +24 -0
  54. package/dist/docs/product-catalog/plans.md +199 -0
  55. package/dist/docs/product-catalog/products.md +60 -0
  56. package/dist/docs/product-catalog/subscriptions.md +29 -0
  57. package/dist/docs/product-catalog/tax-settings.md +37 -0
  58. package/dist/docs/product-catalog/usage-based-billing.md +119 -0
  59. package/dist/docs/promotions/create-a-promotion.md +75 -0
  60. package/dist/docs/promotions/customize-banner.md +41 -0
  61. package/dist/docs/promotions/integrate.md +38 -0
  62. package/dist/docs/promotions/overview.md +51 -0
  63. package/dist/docs/quickstart/core-concepts.md +146 -0
  64. package/dist/docs/quickstart/dashboard-setup.md +129 -0
  65. package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
  66. package/dist/docs/sales/checkout-sessions.md +58 -0
  67. package/dist/docs/sales/orders.md +76 -0
  68. package/dist/http/client.d.ts +28 -0
  69. package/dist/http/client.js +76 -0
  70. package/dist/http/client.js.map +1 -0
  71. package/dist/http/errors.d.ts +20 -0
  72. package/dist/http/errors.js +58 -0
  73. package/dist/http/errors.js.map +1 -0
  74. package/dist/resources/docs-index.d.ts +25 -0
  75. package/dist/resources/docs-index.js +109 -0
  76. package/dist/resources/docs-index.js.map +1 -0
  77. package/dist/resources/index.d.ts +2 -0
  78. package/dist/resources/index.js +73 -0
  79. package/dist/resources/index.js.map +1 -0
  80. package/dist/schemas/kelviq.d.ts +1304 -0
  81. package/dist/schemas/kelviq.js +468 -0
  82. package/dist/schemas/kelviq.js.map +1 -0
  83. package/dist/server.d.ts +2 -0
  84. package/dist/server.js +41 -0
  85. package/dist/server.js.map +1 -0
  86. package/dist/tools/_util.d.ts +15 -0
  87. package/dist/tools/_util.js +15 -0
  88. package/dist/tools/_util.js.map +1 -0
  89. package/dist/tools/checkout.d.ts +3 -0
  90. package/dist/tools/checkout.js +18 -0
  91. package/dist/tools/checkout.js.map +1 -0
  92. package/dist/tools/customers.d.ts +3 -0
  93. package/dist/tools/customers.js +32 -0
  94. package/dist/tools/customers.js.map +1 -0
  95. package/dist/tools/docs.d.ts +2 -0
  96. package/dist/tools/docs.js +43 -0
  97. package/dist/tools/docs.js.map +1 -0
  98. package/dist/tools/entitlements.d.ts +3 -0
  99. package/dist/tools/entitlements.js +22 -0
  100. package/dist/tools/entitlements.js.map +1 -0
  101. package/dist/tools/features.d.ts +3 -0
  102. package/dist/tools/features.js +55 -0
  103. package/dist/tools/features.js.map +1 -0
  104. package/dist/tools/index.d.ts +3 -0
  105. package/dist/tools/index.js +44 -0
  106. package/dist/tools/index.js.map +1 -0
  107. package/dist/tools/licenses.d.ts +3 -0
  108. package/dist/tools/licenses.js +44 -0
  109. package/dist/tools/licenses.js.map +1 -0
  110. package/dist/tools/media.d.ts +3 -0
  111. package/dist/tools/media.js +18 -0
  112. package/dist/tools/media.js.map +1 -0
  113. package/dist/tools/offerings.d.ts +3 -0
  114. package/dist/tools/offerings.js +21 -0
  115. package/dist/tools/offerings.js.map +1 -0
  116. package/dist/tools/partner.d.ts +3 -0
  117. package/dist/tools/partner.js +55 -0
  118. package/dist/tools/partner.js.map +1 -0
  119. package/dist/tools/plan-entitlements.d.ts +3 -0
  120. package/dist/tools/plan-entitlements.js +56 -0
  121. package/dist/tools/plan-entitlements.js.map +1 -0
  122. package/dist/tools/plan-files.d.ts +3 -0
  123. package/dist/tools/plan-files.js +43 -0
  124. package/dist/tools/plan-files.js.map +1 -0
  125. package/dist/tools/plans.d.ts +3 -0
  126. package/dist/tools/plans.js +120 -0
  127. package/dist/tools/plans.js.map +1 -0
  128. package/dist/tools/portal.d.ts +3 -0
  129. package/dist/tools/portal.js +18 -0
  130. package/dist/tools/portal.js.map +1 -0
  131. package/dist/tools/product-files.d.ts +3 -0
  132. package/dist/tools/product-files.js +31 -0
  133. package/dist/tools/product-files.js.map +1 -0
  134. package/dist/tools/product-settings.d.ts +3 -0
  135. package/dist/tools/product-settings.js +31 -0
  136. package/dist/tools/product-settings.js.map +1 -0
  137. package/dist/tools/products.d.ts +3 -0
  138. package/dist/tools/products.js +69 -0
  139. package/dist/tools/products.js.map +1 -0
  140. package/dist/tools/promotions.d.ts +3 -0
  141. package/dist/tools/promotions.js +19 -0
  142. package/dist/tools/promotions.js.map +1 -0
  143. package/dist/tools/subscriptions.d.ts +3 -0
  144. package/dist/tools/subscriptions.js +63 -0
  145. package/dist/tools/subscriptions.js.map +1 -0
  146. package/dist/tools/usage.d.ts +3 -0
  147. package/dist/tools/usage.js +18 -0
  148. package/dist/tools/usage.js.map +1 -0
  149. package/package.json +88 -0
@@ -0,0 +1,1198 @@
1
+ ---
2
+ title: "Python SDK"
3
+ slug: "backend-integration/python-sdk"
4
+ section: "backend-integration"
5
+ description: "Documentation for the Kelviq Python SDK"
6
+ ---
7
+ ## Overview
8
+
9
+ The Kelviq Python SDK provides a convenient way to interact with the Kelviq REST APIs from your Python application. The SDK supports both synchronous and asynchronous operations.
10
+
11
+ ## Installation
12
+
13
+ To install the Kelviq SDK in your environment, run the following command:
14
+
15
+ ```shell
16
+ pip install kelviq-sdk
17
+ ```
18
+
19
+ ## Prerequisites
20
+
21
+ Before you can initialize the client and use the SDK methods, you need a **Server API Key**.
22
+
23
+ You can obtain this key from the Kelviq application:
24
+
25
+ 1. Navigate to Settings.
26
+ 2. Go to the [API keys](https://app.kelviq.com/settings/api-keys) section.
27
+ 3. Copy the **Server API Key**.
28
+
29
+ **Security Warning:** The Server API Key should never be exposed in client-side code. Use it only in your backend services. For client-side applications, use the Client API Key with the [React SDK](/frontend-integration/react-sdk) or [JavaScript SDK](/frontend-integration/js-sdk).
30
+
31
+ Once copied, add this key to your environment variables (recommended for security):
32
+
33
+ ```python
34
+ import os
35
+
36
+ # Example of setting it in your code (environment variables recommended)
37
+ ACCESS_TOKEN = os.environ.get("KELVIQ_SERVER_API_KEY")
38
+ ```
39
+
40
+ ## Configuring the Client
41
+
42
+ The SDK supports both synchronous and asynchronous clients. The primary difference lies in how you create the client instance. Once created, both client types can invoke the same methods to communicate with the Kelviq application.
43
+
44
+ #### How to Create a Synchronous Client
45
+
46
+ Use the synchronous client for traditional, blocking I/O operations.
47
+
48
+ ```python
49
+ from kelviq_sdk import Kelviq
50
+
51
+ client = Kelviq.create_sync_client(access_token=ACCESS_TOKEN)
52
+ ```
53
+
54
+ #### How to Create an Asynchronous Client
55
+ Use the asynchronous client for non-blocking I/O operations, suitable for applications using `asyncio`.
56
+
57
+ ```python
58
+ from kelviq_sdk import Kelviq
59
+
60
+ async_client = Kelviq.create_async_client(access_token=ACCESS_TOKEN)
61
+ ```
62
+
63
+ #### Enum Helpers
64
+
65
+ The SDK provides `ChargePeriod` and `CancellationType` enum classes to prevent typos when passing required string parameters:
66
+
67
+ ```python
68
+ from kelviq_sdk import ChargePeriod, CancellationType
69
+
70
+ # Use enums instead of raw strings
71
+ ChargePeriod.MONTHLY # "MONTHLY"
72
+ CancellationType.IMMEDIATE # "IMMEDIATE"
73
+ ```
74
+
75
+ ## Supported Functionalities
76
+
77
+ The SDK currently supports the following operations:
78
+
79
+ 1. [Customers](/backend-integration/python-sdk#customers)
80
+
81
+ 2. [Checkout](/backend-integration/python-sdk#checkout)
82
+
83
+ 3. [Entitlements](/backend-integration/python-sdk#entitlements)
84
+
85
+ 4. [Reporting](/backend-integration/python-sdk#reporting)
86
+
87
+ 5. [Subscriptions](/backend-integration/python-sdk#subscriptions)
88
+
89
+ 6. [License](/backend-integration/python-sdk#license)
90
+
91
+ 7. [Portal](/backend-integration/python-sdk#portal)
92
+
93
+ ---
94
+
95
+ ## Customers
96
+
97
+ The `customers` module allows you to manage customer records within Kelviq. You can access these operations via the `customers` attribute on an initialized `Kelviq` client instance.
98
+
99
+ All methods are available in both synchronous and asynchronous versions, depending on how the `Kelviq` client was instantiated.
100
+
101
+ ---
102
+
103
+ ### Creates a new customer
104
+
105
+ **Synchronous**:
106
+
107
+ ```python
108
+ new_customer = client.customers.create(
109
+ customerId="unique-customer-id-123",
110
+ email="new.customer@example.com",
111
+ name="John Doe",
112
+ metadata={"source": "sdk_import", "priority": "high"}
113
+ )
114
+ print(f"Customer Created: ID = {new_customer.id}, Customer Client ID = {new_customer.customerId}")
115
+ ```
116
+
117
+ **Asynchronous**:
118
+ ```python
119
+ new_customer = await async_client.customers.create(
120
+ customerId="unique-customer-id-456",
121
+ email="another.new.customer@example.com",
122
+ name="Jane Roe"
123
+ )
124
+ print(f"Customer Created (Async): ID = {new_customer.id}, Customer Client ID = {new_customer.customerId}")
125
+ ```
126
+
127
+ ```json
128
+ {
129
+ "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
130
+ "customerId": "unique-customer-id-123",
131
+ "name": "John Doe",
132
+ "email": "new.customer@example.com",
133
+ "details": {},
134
+ "metadata": {
135
+ "source": "sdk_import",
136
+ "priority": "high"
137
+ },
138
+ "createdOn": "2025-06-04T06:03:30.195790Z",
139
+ "modifiedOn": "2025-06-04T06:03:30.195831Z"
140
+ }
141
+ ```
142
+
143
+ **Required Parameters:**
144
+
145
+ * `customerId` (str): A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.
146
+ * `email` (str): The email address of the customer. Must be a valid email format.
147
+
148
+ **Optional Parameters:**
149
+
150
+ * `name` (str): The name of the customer.
151
+ * `metadata` (Dict[str, str]): A dictionary of custom key-value pairs to store additional information about the customer.
152
+
153
+ **Returns:**
154
+ An instance of `CustomerResponse` (Pydantic model), representing the newly created customer record. Key attributes include:
155
+
156
+ * `id` (str): The server-generated unique UUID for the customer record.
157
+ * `customerId` (str): The client-provided customer identifier.
158
+ * `name` (str): The customer's name.
159
+ * `email` (str): The customer's email.
160
+ * `details` ([Dict[str, Any]]): Any server-added details about the customer (typically read-only).
161
+ * `metadata` ([Dict[str, str]]): The metadata associated with the customer.
162
+ * `createdOn` (string) : ISO 8601 timestamp of when the customer was created.
163
+ * `modifiedOn` (string) : ISO 8601 timestamp of when the customer was last modified.
164
+
165
+ ### Updates an existing customer
166
+
167
+ This operation performs a partial update (PATCH), so you only need to provide the fields you want to change.
168
+
169
+ **Synchronous**:
170
+
171
+ ```python
172
+ updated_customer = client.customers.update(
173
+ customerId="unique-customer-id-123",
174
+ name="Johnathan Doe",
175
+ metadata={"source": "sdk_import", "priority": "very_high", "status": "active"}
176
+ )
177
+ print(f"Customer Updated: {updated_customer.name}")
178
+ ```
179
+
180
+ **Asynchronous**:
181
+
182
+ ```python
183
+ updated_customer = await async_client.customers.update(
184
+ customerId="unique-customer-id-456",
185
+ email="jane.roe.updated@example.com"
186
+ )
187
+ print(f"Customer Updated (Async): {updated_customer.email}")
188
+ ```
189
+
190
+ ```json
191
+ {
192
+ "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
193
+ "customerId": "unique-customer-id-123",
194
+ "name": "Johnathan Doe",
195
+ "email": "new.customer@example.com",
196
+ "details": {},
197
+ "metadata": {
198
+ "source": "sdk_import",
199
+ "priority": "high",
200
+ "status": "active"
201
+ },
202
+ "createdOn": "2025-06-04T06:03:30.195790Z",
203
+ "modifiedOn": "2025-06-04T06:03:30.195831Z"
204
+ }
205
+ ```
206
+
207
+ **Parameters:**
208
+
209
+ **Required Parameters:**
210
+
211
+ * `customerId` (str): A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.
212
+
213
+ **Optional Parameters:**
214
+
215
+ * `email` (str): The email address of the customer. Must be a valid email format.
216
+ * `name` (str): The name of the customer.
217
+ * `metadata` (Dict[str, str]): A dictionary of custom key-value pairs to store additional information about the customer.
218
+
219
+ **Returns:**
220
+ An instance of `CustomerResponse` (Pydantic model), representing the **updated** customer record. Key attributes include:
221
+
222
+ * `id` (str): The server-generated unique UUID for the customer record.
223
+ * `customerId` (str): The client-provided customer identifier.
224
+ * `name` (str): The customer's name.
225
+ * `email` (str): The customer's email.
226
+ * `details` ([Dict[str, Any]]): Any server-added details about the customer (typically read-only).
227
+ * `metadata` ([Dict[str, Any]]): The metadata associated with the customer.
228
+ * `createdOn` (string) : ISO 8601 timestamp of when the customer was created.
229
+ * `modifiedOn` (string) : ISO 8601 timestamp of when the customer was last modified.
230
+
231
+ ---
232
+
233
+ ## Checkout
234
+
235
+ The checkout module provides functionalities for creating and managing checkout sessions. You can access these operations via the checkout attribute on an initialized Kelviq client instance.
236
+
237
+ `create_session(...)`
238
+ This operation creates a new checkout session for a customer, allowing them to proceed with a purchase or subscription.
239
+
240
+ **Synchronous**:
241
+
242
+ ```python
243
+ response = client.checkout.create_session(
244
+ planIdentifier="plan-pro-monthly",
245
+ chargePeriod="MONTHLY",
246
+ customerId="cust_789", # Recommended, otherwise it will create a new customer
247
+ successUrl="https://kelviq.com/checkout/success"
248
+ )
249
+ print(f"Checkout Session URL: {response.checkoutUrl}")
250
+ ```
251
+
252
+ **Asynchronous**:
253
+
254
+ ```python
255
+ response = await async_client.checkout.create_session(
256
+ planIdentifier="plan-pro-monthly",
257
+ chargePeriod="MONTHLY",
258
+ customerId="cust_789",
259
+ successUrl="https://kelviq.com/checkout/success",
260
+ offeringId="96d3a293-34ac-48a5-b73d-976b15781afd",
261
+ pricingTableId="6db2717a-4e43-4ae1-a293-6c0a775f6264",
262
+ ruleId="f2ebc23f-3f79-4cf4-b17e-fe8e30a42ab2",
263
+ features=[{'identifier':"seats", 'quantity': 5}],
264
+ ipAddress="103.154.35.20",
265
+ )
266
+ print(f"Checkout Session URL: {response.checkoutUrl}")
267
+
268
+ ```
269
+
270
+ ```json
271
+ {
272
+ "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
273
+ "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
274
+ }
275
+ ```
276
+
277
+ **Required Parameters:**
278
+
279
+ * `planIdentifier` (str): The identifier of the specific plan the customer is checking out with. planIdentifier is mandatory.
280
+
281
+ * `successUrl` (str): The URL to which the user will be redirected after a successful checkout.
282
+
283
+ * `chargePeriod` (str | ChargePeriod): Required. The billing cycle for the subscription. You can use the `ChargePeriod` enum (e.g., `ChargePeriod.MONTHLY`) or a raw string. Must be one of:
284
+
285
+ * `"ONE_TIME"` / `ChargePeriod.ONE_TIME`
286
+
287
+ * `"MONTHLY"` / `ChargePeriod.MONTHLY`
288
+
289
+ * `"YEARLY"` / `ChargePeriod.YEARLY`
290
+
291
+ * `"WEEKLY"` / `ChargePeriod.WEEKLY`
292
+
293
+ * `"DAILY"` / `ChargePeriod.DAILY`
294
+
295
+ * `"THREE_MONTHS"` / `ChargePeriod.THREE_MONTHS`
296
+
297
+ * `"SIX_MONTHS"` / `ChargePeriod.SIX_MONTHS`
298
+
299
+ **Optional Parameters:**
300
+
301
+ * `offeringId` (str): The ID (uuid) of the offering the customer is checking out with.
302
+
303
+ * `pricingTableId` (str): Required. The id (uuid) of the pricingTable being used for this checkout. (Considered only if `offeringId` is not provided)
304
+
305
+ * `ruleId` (str): Required. The id (uuid) of the pricing rule being applied. (Considered only if `offeringId` is not provided)
306
+
307
+ * `customerId` (str): Required. The ID of the customer initiating the checkout. (If not provided, a new customer will be created)
308
+
309
+ * `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:
310
+ * `"identifier"` (str): The unique identifier for the feature.
311
+ * `"quantity"` (int): The desired quantity for this feature.
312
+ * Example: `[{"identifier": "seats", "quantity": 10}, {"identifier": "api-calls-tier1", "quantity": 5000}]`
313
+
314
+ * `ipAddress` (str): The IP Address of the customer, used for location based pricing.
315
+
316
+ * `currencyCode` (str): The currency code for the checkout session (e.g. `"USD"`). Required when `customAmount` is provided.
317
+
318
+ * `customAmount` (float): A custom amount to charge for this checkout session. When provided, `taxBehavior` and `currencyCode` are also required.
319
+
320
+ * `taxBehavior` (str): Specifies how taxes are applied to the `customAmount`. Required when `customAmount` is provided. Must be one of:
321
+ * `"INCLUSIVE"` — Tax is included in the custom amount.
322
+ * `"EXCLUSIVE"` — Tax is added on top of the custom amount.
323
+
324
+ * `discountsEnabled` (bool): Whether the discount/coupon code field is shown on the checkout page. Defaults to `True`.
325
+
326
+ * `lockEmail` (bool): When `True`, the email field is pre-filled and locked so the customer cannot change it. Defaults to `False`.
327
+
328
+ * `defaultBillingCountry` (str): ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`) used to pre-fill the billing address country on the checkout page.
329
+
330
+ **Returns**:
331
+
332
+ An instance of CreateCheckoutSessionResponse (Pydantic model), which includes:
333
+
334
+ * `checkoutSessionId` (str): The unique ID for the created checkout session.
335
+
336
+ * `checkoutUrl` (str): The URL that the customer should be redirected to in order to complete the payment and activate the subscription/purchase.
337
+
338
+ ---
339
+
340
+ ## Entitlements
341
+
342
+ The entitlements module allows you to check and retrieve customer entitlements for various features. These operations target a specific edge API endpoint ( `https://edge.api.kelviq.com` by default) and use the GET HTTP method with query parameters.
343
+
344
+ ### Checks if a specific customer has access to a particular feature.
345
+ This method directly returns a boolean indicating access status.
346
+
347
+ **Synchronous**:
348
+
349
+ ```python
350
+ has_feature_access = client.entitlements.has_access(
351
+ customerId="cust_123",
352
+ featureId="premium-reporting"
353
+ )
354
+ ```
355
+
356
+ **Asynchronous**:
357
+
358
+ ```python
359
+ has_feature_access = await async_client.entitlements.has_access(
360
+ customerId="cust_456",
361
+ featureId="advanced-analytics"
362
+ )
363
+ ```
364
+
365
+ ```shell
366
+ True
367
+ ```
368
+
369
+ **Required Parameters**:
370
+
371
+ * `customerId` (str): The unique identifier for the customer.
372
+
373
+ * `featureId` (str): The unique identifier for the feature whose access is being checked.
374
+
375
+ **Returns**:
376
+
377
+ * `bool`: True if the customer has access to the specified feature (considering feature type, limits, etc.), False otherwise or if the feature is not found in their entitlements.
378
+
379
+ ### Retrieves the detailed entitlement information for a specific feature for a given customer.
380
+
381
+ **Synchronous**:
382
+
383
+ ```python
384
+ entitlement_response = client.entitlements.get_entitlement(
385
+ customerId="cust_123",
386
+ featureId="premium-reporting"
387
+ )
388
+ ```
389
+
390
+ **Asynchronous**:
391
+
392
+ ```python
393
+ entitlement_response = await async_client.entitlements.get_entitlement(
394
+ customerId="cust_456",
395
+ featureId="advanced-analytics"
396
+ )
397
+ ```
398
+
399
+ ```python
400
+ Entitlement(
401
+ featureId="advanced-analytics",
402
+ featureType="METER",
403
+ hasAccess=True,
404
+ hardLimit=False,
405
+ usageLimit=3,
406
+ currentUsage=0,
407
+ remaining=3,
408
+ items=[
409
+ EntitlementDetail(featureId="advanced-analytics", featureType="METER", hasAccess=True, resetAt="2025-05-22 08:27:45", hardLimit=False, usageLimit=3, currentUsage=0, remaining=3)
410
+ ]
411
+ )
412
+ ```
413
+
414
+ **Required Parameters**:
415
+
416
+ * `customerId` (str): The unique identifier for the customer.
417
+
418
+ * `featureId` (str): The unique identifier for the feature whose access is being checked.
419
+
420
+ **Returns**:
421
+
422
+ An `Entitlement` model (Pydantic), or `None` if the feature is not found. If the customer has multiple subscriptions, there can be multiple raw entries for the same featureId. The SDK aggregates these into a single model and keeps the raw entries accessible via the `items` attribute.
423
+
424
+ The aggregated `Entitlement` model includes:
425
+
426
+ * `featureId` (str): The feature ID.
427
+
428
+ * `featureType` (str): The type of the feature — `"METER"`, `"BOOLEAN"`, or `"CUSTOMIZABLE"`.
429
+
430
+ * `hasAccess` (bool): For **METER** features, computed as `remaining is None or remaining > 0`. For **BOOLEAN** and **CUSTOMIZABLE** features, `True` if any raw entry grants access.
431
+
432
+ * `hardLimit` (Optional[bool]): For **METER**, `True` if any entry has a hard limit. For **BOOLEAN**, always `False`.
433
+
434
+ * `usageLimit` (Optional[int]): For **METER**, summed across all items. For **CUSTOMIZABLE**, taken from the first item. For **BOOLEAN**, always `None`.
435
+
436
+ * `currentUsage` (Optional[int]): For **METER**, summed across all items. For **CUSTOMIZABLE**, taken from the first item. For **BOOLEAN**, always `0`.
437
+
438
+ * `remaining` (Optional[int]): For **METER**, computed as `usageLimit - currentUsage`. For **CUSTOMIZABLE**, taken from the first item. For **BOOLEAN**, always `None`.
439
+
440
+ * `items` (List[EntitlementDetail]): The raw entitlement entries from the API. Each item retains its own `resetAt` value, since reset dates can differ across subscriptions.
441
+
442
+ ### Retrieves all aggregated entitlements for a given customer.
443
+
444
+ **Synchronous**:
445
+
446
+ ```python
447
+ entitlements = client.entitlements.get_entitlements(
448
+ customerId="cust_123"
449
+ )
450
+ # Access by feature ID
451
+ if "premium-reporting" in entitlements:
452
+ ent = entitlements["premium-reporting"]
453
+ print(f"hasAccess={ent.hasAccess}, items={len(ent.items)}")
454
+ ```
455
+
456
+ **Asynchronous**:
457
+
458
+ ```python
459
+ entitlements = await async_client.entitlements.get_entitlements(
460
+ customerId="cust_456"
461
+ )
462
+ for feature_id, ent in entitlements.items():
463
+ print(f"{feature_id}: hasAccess={ent.hasAccess}, items={len(ent.items)}")
464
+ ```
465
+
466
+ **Required Parameters**:
467
+
468
+ * `customerId` (str): The unique identifier for the customer.
469
+
470
+ **Returns**:
471
+
472
+ A `Dict[str, Entitlement]` keyed by `featureId`, where each value is an aggregated `Entitlement` model with an `.items` list containing the raw entries. See `get_entitlement` above for the full model structure.
473
+
474
+ ### Retrieves the raw entitlement response for a specific feature (no aggregation).
475
+
476
+ **Synchronous**:
477
+
478
+ ```python
479
+ raw_response = client.entitlements.get_raw_entitlement(
480
+ customerId="cust_123",
481
+ featureId="premium-reporting"
482
+ )
483
+ print(f"Customer: {raw_response.customerId}")
484
+ for detail in raw_response.entitlements:
485
+ print(f" {detail.featureId}: {detail.hasAccess}")
486
+ ```
487
+
488
+ **Asynchronous**:
489
+
490
+ ```python
491
+ raw_response = await async_client.entitlements.get_raw_entitlement(
492
+ customerId="cust_456",
493
+ featureId="advanced-analytics"
494
+ )
495
+ ```
496
+
497
+ **Required Parameters**:
498
+
499
+ * `customerId` (str): The unique identifier for the customer.
500
+
501
+ * `featureId` (str): The unique identifier for the feature.
502
+
503
+ **Returns**:
504
+
505
+ An instance of `CheckEntitlementsResponse` (Pydantic model) containing the raw API response without aggregation:
506
+
507
+ * `customerId` (str): The customer's ID.
508
+
509
+ * `entitlements` (List[EntitlementDetail]): The raw list of entitlement entries.
510
+
511
+ ### Retrieves all raw entitlements for a given customer (no aggregation).
512
+
513
+ **Synchronous**:
514
+
515
+ ```python
516
+ raw_response = client.entitlements.get_raw_entitlements(
517
+ customerId="cust_123"
518
+ )
519
+ ```
520
+
521
+ **Asynchronous**:
522
+
523
+ ```python
524
+ raw_response = await async_client.entitlements.get_raw_entitlements(
525
+ customerId="cust_456"
526
+ )
527
+ ```
528
+
529
+ ```json
530
+ {
531
+ "customerId": "cust_456",
532
+ "entitlements": [
533
+ {
534
+ "featureId": "advanced-analytics",
535
+ "featureType": "METER",
536
+ "hasAccess": true,
537
+ "resetAt": "2025-05-22 08:27:45",
538
+ "hardLimit": false,
539
+ "usageLimit": 3,
540
+ "currentUsage": 0,
541
+ "remaining": 3
542
+ }
543
+ ]
544
+ }
545
+ ```
546
+
547
+ **Required Parameters**:
548
+
549
+ * `customerId` (str): The unique identifier for the customer.
550
+
551
+ **Returns**:
552
+
553
+ An instance of `CheckEntitlementsResponse` (Pydantic model) containing the raw API response without aggregation:
554
+
555
+ * `customerId` (str): The customer's ID.
556
+
557
+ * `entitlements` (List[EntitlementDetail]): The raw list of entitlement entries. Each `EntitlementDetail` has fields like:
558
+
559
+ * `featureId`: str
560
+
561
+ * `hasAccess`: bool
562
+
563
+ * `featureType`: str
564
+
565
+ * `resetAt`: str
566
+
567
+ * `hardLimit`: Optional[bool]
568
+
569
+ * `usageLimit`: Optional[int]
570
+
571
+ * `currentUsage`: Optional[int]
572
+
573
+ * `remaining`: Optional[int]
574
+
575
+ ---
576
+
577
+ ## Reporting
578
+
579
+ ### Reporting pre-aggregated usages for customer
580
+
581
+ This endpoint is used for reporting the pre-aggregated feature usage from your application (client-level) to the Kelviq application. It allows you to update the usage count for a specific feature associated with a customer.
582
+
583
+ **Synchronous**:
584
+
585
+ ```python
586
+ # Assuming 'client' is your synchronous Kelviq client
587
+ response = client.reporting.report_usage(
588
+ value=150,
589
+ customerId="customer_001",
590
+ featureId="seats",
591
+ behaviour="SET" # Or 'DELTA'
592
+ )
593
+ ```
594
+
595
+ **Asynchronous**:
596
+
597
+ ```python
598
+ # Assuming 'async_client' is your asynchronous Kelviq client
599
+ response = await async_client.reporting.report_usage(
600
+ value=75,
601
+ customerId="customer_001",
602
+ featureId="seats",
603
+ behaviour="DELTA"
604
+ )
605
+ ```
606
+
607
+ ```json
608
+ {
609
+ "value": 150,
610
+ "customerId": "customer_001",
611
+ "featureId": "seats",
612
+ "behaviour": "SET",
613
+ "orgId": "1",
614
+ "eventName": "aggregated.usage",
615
+ "idempotencyKey": "597ee95063c744ed9bcc9b1cf5676a8a",
616
+ "timestamp": "2025-05-22 08:27:45.430732"
617
+ }
618
+ ```
619
+
620
+ **Required Parameters**:
621
+
622
+ * `value` (int): The usage value being reported.
623
+
624
+ * `customerId` (str): The unique identifier for the customer associated with this usage.
625
+
626
+ * `featureId` (str): The unique identifier for the feature for which usage is being reported.
627
+
628
+ * `behaviour` parameter dictates how the usage is updated:
629
+
630
+ * `SET`: This will replace the current usage value for the feature with the new `value` provided.
631
+
632
+ * `DELTA`: This will increment the existing usage value for the feature by the amount specified in the `value` parameter
633
+
634
+ **Returns**:
635
+
636
+ An instance of ReportUsageResponse (Pydantic model), which includes:
637
+
638
+ * `value` (int): The usage value that was recorded.
639
+
640
+ * `customerId` (str): The customer ID associated with the usage.
641
+
642
+ * `featureId` (str): The feature Identifier for which usage was recorded.
643
+
644
+ * `behaviour` (str): The behaviour type ("SET" or "DELTA") that was processed.
645
+
646
+ * `orgId` (str): The organization ID associated with this record, as determined by the server.
647
+
648
+ * `eventName` (str): An internal event name generated by the server for this usage report (e.g., "aggregated.usage").
649
+
650
+ * `idempotencyKey` (str): A unique idempotency key generated by the server for this specific usage report instance.
651
+
652
+ * `timestamp` (str): The server-generated UTC timestamp (str format) indicating when the usage report was processed.
653
+
654
+ ## Subscriptions
655
+
656
+ The subscriptions module allows you to manage customer subscriptions, including updates and cancellation. You can access these operations via the `subscriptions` attribute on an initialized Kelviq client instance.
657
+
658
+ ### Updates an existing subscription to a new plan
659
+
660
+ **Synchronous**:
661
+
662
+ ```python
663
+ # Assuming 'client' is your synchronous Kelviq client
664
+ try:
665
+ response = client.subscriptions.update(
666
+ subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
667
+ planIdentifier="premium-plan",
668
+ chargePeriod="MONTHLY",
669
+ )
670
+ print(response.subscriptionId)
671
+ except Exception as e:
672
+ print(f"Error updating subscription: {e}")
673
+ ```
674
+
675
+ **Asynchronous**:
676
+
677
+ ```python
678
+ # Assuming 'async_client' is your asynchronous Kelviq client
679
+ try:
680
+ response = await async_client.subscriptions.update(
681
+ subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
682
+ planIdentifier="new_plan_enterprise",
683
+ chargePeriod="YEARLY",
684
+ offeringId="offer_abc",
685
+ pricingTableId="pw_def",
686
+ ruleId="rule_ghi",
687
+ ipAddress="103.154.35.20",
688
+ features=[{'identifier': "seats", 'quantity': 10}],
689
+ trialEnd="2025-12-31 23:59:59" # or "now" to end the trial immediately
690
+ )
691
+ print(response.subscriptionId)
692
+ except Exception as e:
693
+ print(f"Error updating subscription: {e}")
694
+ ```
695
+
696
+ ```json
697
+ {
698
+ "subscriptionId": "dffaf07e-4517-47db-ba3a-59a05aa2d465"
699
+ }
700
+ ```
701
+
702
+ **Required Parameters**:
703
+
704
+ * `subscriptionId` (str): Required. The unique identifier of the subscription to be updated.
705
+ * `planIdentifier` (str): Required. The identifier of the new plan.
706
+ * `chargePeriod` (str | ChargePeriod): Required. The new charging period for the subscription. You can use the `ChargePeriod` enum (e.g., `ChargePeriod.MONTHLY`) or a raw string. Must be one of:
707
+ * `"ONE_TIME"` / `ChargePeriod.ONE_TIME`
708
+ * `"MONTHLY"` / `ChargePeriod.MONTHLY`
709
+ * `"YEARLY"` / `ChargePeriod.YEARLY`
710
+ * `"WEEKLY"` / `ChargePeriod.WEEKLY`
711
+ * `"DAILY"` / `ChargePeriod.DAILY`
712
+ * `"THREE_MONTHS"` / `ChargePeriod.THREE_MONTHS`
713
+ * `"SIX_MONTHS"` / `ChargePeriod.SIX_MONTHS`
714
+
715
+ **Optional Parameters:**
716
+
717
+ * `offeringId` (str): Optional. The ID of the new offering, if applicable.
718
+ * `pricingTableId` (str): Optional. The ID of the new pricingTable, if applicable.
719
+ * `ruleId` (str): Optional. The ID of the new pricing rule, if applicable.
720
+ * `ipAddress` (str): The IP Address of the customer, used for location based pricing.
721
+ * `features` ([List[Dict[str, Any]]]): Optional. A list of dictionaries, where each dictionary represents a feature and its desired quantity to update for the subscription. Each dictionary **must** have two keys:
722
+ * `"identifier"` (str): The unique identifier for the feature.
723
+ * `"quantity"` (int): The desired quantity for this feature.
724
+ * Example: `[{'identifier': 'seats', 'quantity': 10}, {'identifier': 'projects', 'quantity': 5}]`
725
+ * `trialEnd` (str): Optional. Controls the trial period for the updated subscription. Accepts either:
726
+ * The literal string `"now"` to end any active trial immediately.
727
+ * An ISO 8601 datetime string (e.g. `"2025-12-31 23:59:59"`) to set a new trial end date. The datetime must be in the future. Naive datetimes are interpreted as UTC.
728
+ * If omitted, the existing trial behavior on the subscription is preserved.
729
+
730
+ **Returns**:
731
+
732
+ An instance of `UpdateSubscriptionResponse`, which includes:
733
+
734
+ * `subscriptionId` (str): UUID of the updated subscription.
735
+
736
+ ### Cancel an active subscription for a customer.
737
+
738
+ **Synchronous**:
739
+
740
+ ```python
741
+ # Assuming 'client' is your synchronous Kelviq client
742
+ try:
743
+ response = client.subscriptions.cancel(
744
+ subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
745
+ cancellationType="CURRENT_PERIOD_ENDS" # Or "IMMEDIATE", "SPECIFIC_DATE"
746
+ # cancellationDate="2025-12-31" # Required if cancellationType is "SPECIFIC_DATE"
747
+ )
748
+ print(response.message)
749
+ except Exception as e:
750
+ print(f"Error cancelling subscription: {e}")
751
+ ```
752
+
753
+ **Asynchronous**:
754
+
755
+ ```python
756
+ # Assuming 'async_client' is your asynchronous Kelviq client
757
+ try:
758
+ response = await async_client.subscriptions.cancel(
759
+ subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
760
+ cancellationType="IMMEDIATE"
761
+ )
762
+ print(response.message)
763
+ except Exception as e:
764
+ print(f"Error cancelling subscription: {e}")
765
+ ```
766
+
767
+ ```json
768
+ {
769
+ "message": "Subscription cancellation processed successfully."
770
+ }
771
+ ```
772
+
773
+ **Required Parameters**:
774
+
775
+ * `subscriptionId` (str): The unique identifier of the subscription to be cancelled.
776
+
777
+ * `cancellationType` (str | CancellationType): The type of cancellation to perform. You can use the `CancellationType` enum (e.g., `CancellationType.CURRENT_PERIOD_ENDS`) or a raw string. Must be one of:
778
+
779
+ * `"IMMEDIATE"` / `CancellationType.IMMEDIATE`: The subscription is cancelled immediately.
780
+ * `"CURRENT_PERIOD_ENDS"` / `CancellationType.CURRENT_PERIOD_ENDS`: The subscription will remain active until the end of the current billing period and then cancel.
781
+ * `"SPECIFIC_DATE"` / `CancellationType.SPECIFIC_DATE`: The subscription will be cancelled on the specified `cancellationDate`.
782
+
783
+ * `cancellationDate` (str): The specific date for cancellation if `cancellationType` is `"SPECIFIC_DATE"`. Must be in `YYYY-MM-DD` format. This parameter is **required** if `cancellationType` is `"SPECIFIC_DATE"`.
784
+
785
+ **Returns**:
786
+
787
+ An instance of `CancelSubscriptionResponse`, which includes:
788
+
789
+ * `message` (str): A confirmation message indicating the result of the cancellation request.
790
+
791
+ ---
792
+
793
+ ## License
794
+
795
+ The `license` module allows you to activate, deactivate, and validate software licenses. You can access these operations via the `license` attribute on an initialized `Kelviq` client instance.
796
+
797
+ All methods are available in both synchronous and asynchronous versions, depending on how the `Kelviq` client was instantiated.
798
+
799
+ ---
800
+
801
+ ### Activate a license key
802
+
803
+ Creates a new license instance for a given license key, optionally associating it with a customer.
804
+
805
+ **Synchronous**:
806
+
807
+ ```python
808
+ response = client.license.activate(
809
+ licenseKey="LIC-XXXX-YYYY-ZZZZ",
810
+ customerId="cust_789",
811
+ instanceName="My MacBook Pro",
812
+ metadata={"os": "macOS", "arch": "arm64"}
813
+ )
814
+ print(f"Instance ID: {response.instanceId}")
815
+ print(f"License key: {response.license.licenseKey}")
816
+ ```
817
+
818
+ **Asynchronous**:
819
+
820
+ ```python
821
+ response = await async_client.license.activate(
822
+ licenseKey="LIC-XXXX-YYYY-ZZZZ",
823
+ customerId="cust_789",
824
+ instanceName="My MacBook Pro",
825
+ )
826
+ print(f"Instance ID: {response.instanceId}")
827
+ ```
828
+
829
+ ```json
830
+ {
831
+ "instanceId": "8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
832
+ "activatedAt": "2026-01-27T10:33:00Z",
833
+ "expiresOn": "2027-01-27T10:33:00Z",
834
+ "license": {
835
+ "id": "7be7a5b6-7a0e-4178-a085-8ef48f0649ab",
836
+ "licenseKey": "LIC-A8D5F89E-B46B-472C-9BED-66EE2545B85E",
837
+ "activatedOn": "2026-01-22T03:26:56Z",
838
+ "expiresOn": "2026-01-23T03:26:56Z",
839
+ "activationUsage": 1,
840
+ "activationLimit": 4,
841
+ "enabled": true,
842
+ "customer": {
843
+ "customerId": "cfa95cf8c8d24e8b9d3d2d1ada98a94d",
844
+ "name": "Geo",
845
+ "email": "geo@kelviq.com"
846
+ },
847
+ "plan": {
848
+ "identifier": "pro-yearly",
849
+ "name": "Pro Yearly",
850
+ "description": "Pro plan billed yearly",
851
+ "product": {
852
+ "id": "d970ab2d-834f-4c52-8742-2e6ed7e8a31f",
853
+ "identifier": "kelviq-engine",
854
+ "name": "Kelviq Engine",
855
+ "taxCode": "software",
856
+ "createdOn": "2025-01-01T00:00:00Z",
857
+ "modifiedOn": "2025-06-01T00:00:00Z"
858
+ },
859
+ "version": 1,
860
+ "isLatest": true
861
+ },
862
+ "subscription": {
863
+ "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
864
+ "recurrence": "1 month",
865
+ "billingPeriodStartTime": "2026-01-22T03:26:56Z",
866
+ "billingPeriodEndTime": "2026-02-22T03:26:56Z",
867
+ "startDate": "2026-01-22",
868
+ "endDate": null,
869
+ "status": "active",
870
+ "amount": "49.00",
871
+ "currency": "usd",
872
+ "trialDaysRemaining": 0,
873
+ "billingType": "SUBSCRIPTION",
874
+ "recurrenceUnit": 1,
875
+ "recurrenceType": "MONTH"
876
+ }
877
+ }
878
+ }
879
+ ```
880
+
881
+ **Required Parameters:**
882
+
883
+ * `licenseKey` (str): The license key string to activate.
884
+
885
+ **Optional Parameters:**
886
+
887
+ * `customerId` (str): The ID of the customer this instance is associated with.
888
+ * `instanceName` (str): A human-readable name for this instance (e.g. device name).
889
+ * `metadata` (Dict[str, Any]): A dictionary of custom key-value pairs to attach to the instance.
890
+
891
+ **Returns:**
892
+
893
+ An instance of `LicenseActivateResponse` (Pydantic model), which includes:
894
+
895
+ * `instanceId` (str): The unique ID of the newly created license instance.
896
+ * `activatedAt` (str): ISO 8601 timestamp of when the instance was activated.
897
+ * `expiresOn` (Optional[str]): ISO 8601 timestamp of when the instance expires, if applicable.
898
+ * `license` (`LicenseDetails`): The full license object. Key fields:
899
+ * `id` (str): Server-generated UUID for the license.
900
+ * `licenseKey` (str): The license key string.
901
+ * `activatedOn` (Optional[str]): ISO 8601 timestamp of when the license was first activated.
902
+ * `expiresOn` (Optional[str]): ISO 8601 timestamp of when the license expires.
903
+ * `activationUsage` (int): Number of currently active instances.
904
+ * `activationLimit` (int): Maximum number of allowed concurrent activations.
905
+ * `enabled` (bool): Whether the license is active.
906
+ * `customer` (Optional[object]): The associated customer, if any. Fields: `customerId`, `name`, `email`.
907
+ * `plan` (Optional[object]): The plan associated with this license, if any. Fields: `identifier`, `name`, `description`, `version`, `isLatest`, and `product` (object with `id`, `identifier`, `name`, `taxCode`, `createdOn`, `modifiedOn`).
908
+ * `subscription` (Optional[object]): Subscription details, if any. Fields: `id`, `recurrence`, `billingPeriodStartTime`, `billingPeriodEndTime`, `startDate`, `endDate`, `status`, `amount`, `currency`, `trialDaysRemaining`, `billingType`, `recurrenceUnit`, `recurrenceType`.
909
+
910
+ ---
911
+
912
+ ### Deactivate a license instance
913
+
914
+ Deactivates a specific license instance by its instance ID.
915
+
916
+ **Synchronous**:
917
+
918
+ ```python
919
+ try:
920
+ response = client.license.deactivate(
921
+ licenseKey="LIC-XXXX-YYYY-ZZZZ",
922
+ instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5a6b"
923
+ )
924
+ print(response.message)
925
+ except Exception as e:
926
+ print(f"Error deactivating license: {e}")
927
+ ```
928
+
929
+ **Asynchronous**:
930
+
931
+ ```python
932
+ try:
933
+ response = await async_client.license.deactivate(
934
+ licenseKey="LIC-XXXX-YYYY-ZZZZ",
935
+ instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5a6b"
936
+ )
937
+ print(response.message)
938
+ except Exception as e:
939
+ print(f"Error deactivating license: {e}")
940
+ ```
941
+
942
+ ```json
943
+ {
944
+ "message": "License instance deactivated successfully.",
945
+ "deactivatedAt": "2026-01-27T10:35:00Z"
946
+ }
947
+ ```
948
+
949
+ **Required Parameters:**
950
+
951
+ * `licenseKey` (str): The license key string.
952
+ * `instanceId` (str): The unique ID of the instance to deactivate.
953
+
954
+ **Returns:**
955
+
956
+ An instance of `LicenseDeactivateResponse` (Pydantic model), which includes:
957
+
958
+ * `message` (str): Confirmation message.
959
+ * `deactivatedAt` (str): ISO 8601 timestamp of when the instance was deactivated.
960
+
961
+ ---
962
+
963
+ ### Validate a license key
964
+
965
+ Checks whether a license key (and optionally a specific instance) is valid.
966
+
967
+ **Synchronous**:
968
+
969
+ ```python
970
+ response = client.license.validate(
971
+ licenseKey="LIC-XXXX-YYYY-ZZZZ",
972
+ instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5a6b" # optional
973
+ )
974
+
975
+ if response.valid:
976
+ print(f"License is valid: {response.code}")
977
+ else:
978
+ print(f"License invalid: {response.detail}")
979
+ ```
980
+
981
+ **Asynchronous**:
982
+
983
+ ```python
984
+ response = await async_client.license.validate(
985
+ licenseKey="LIC-XXXX-YYYY-ZZZZ"
986
+ )
987
+ print(f"Valid: {response.valid}, Code: {response.code}")
988
+ ```
989
+
990
+ ```json
991
+ {
992
+ "valid": true,
993
+ "code": "VALID",
994
+ "detail": "Instance ID valid for this license.",
995
+ "metadata": {
996
+ "os": "macOS",
997
+ "arch": "arm64"
998
+ },
999
+ "license": {
1000
+ "id": "7be7a5b6-7a0e-4178-a085-8ef48f0649ab",
1001
+ "licenseKey": "LIC-A8D5F89E-B46B-472C-9BED-66EE2545B85E",
1002
+ "activatedOn": "2026-01-22T03:26:56Z",
1003
+ "expiresOn": "2026-01-23T03:26:56Z",
1004
+ "activationUsage": 1,
1005
+ "activationLimit": 4,
1006
+ "enabled": true,
1007
+ "customer": {
1008
+ "customerId": "cfa95cf8c8d24e8b9d3d2d1ada98a94d",
1009
+ "name": "Geo",
1010
+ "email": "geo@kelviq.com"
1011
+ },
1012
+ "plan": {
1013
+ "identifier": "pro-yearly",
1014
+ "name": "Pro Yearly",
1015
+ "product": {
1016
+ "id": "d970ab2d-834f-4c52-8742-2e6ed7e8a31f",
1017
+ "identifier": "kelviq-engine",
1018
+ "name": "Kelviq Engine",
1019
+ "taxCode": "software"
1020
+ }
1021
+ },
1022
+ "subscription": {
1023
+ "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
1024
+ "recurrence": "1 month",
1025
+ "billingPeriodStartTime": "2026-01-22T03:26:56Z",
1026
+ "billingPeriodEndTime": "2026-02-22T03:26:56Z",
1027
+ "startDate": "2026-01-22",
1028
+ "endDate": null,
1029
+ "status": "active",
1030
+ "amount": "49.00",
1031
+ "currency": "usd",
1032
+ "trialDaysRemaining": 0,
1033
+ "billingType": "SUBSCRIPTION",
1034
+ "recurrenceUnit": 1,
1035
+ "recurrenceType": "MONTH"
1036
+ }
1037
+ }
1038
+ }
1039
+ ```
1040
+
1041
+ **Required Parameters:**
1042
+
1043
+ * `licenseKey` (str): The license key string to validate.
1044
+
1045
+ **Optional Parameters:**
1046
+
1047
+ * `instanceId` (str): If provided, also validates that this specific instance is active for the given license key.
1048
+
1049
+ **Returns:**
1050
+
1051
+ An instance of `LicenseValidateResponse` (Pydantic model), which includes:
1052
+
1053
+ * `valid` (bool): Whether the license (and instance, if provided) is valid.
1054
+ * `code` (str): A short status code (e.g. `"VALID"`, `"INVALID"`, `"EXPIRED"`).
1055
+ * `detail` (str): A human-readable description of the validation result.
1056
+ * `metadata` (Optional[Dict[str, Any]]): Any metadata attached to the instance, if applicable.
1057
+ * `license` (Optional[`LicenseDetails`]): The full license object (same structure as in `activate`), or `None` if not found.
1058
+
1059
+ ---
1060
+
1061
+ ## Portal
1062
+
1063
+ The portal module allows you to create authenticated customer portal sessions. Once a session is created, you can redirect your customer directly to their self-serve customer portal without requiring them to log in manually. You can access these operations via the `portal` attribute on an initialized `Kelviq` client instance.
1064
+
1065
+ All methods are available in both synchronous and asynchronous versions, depending on how the `Kelviq` client was instantiated.
1066
+
1067
+ ### Creates a new customer portal session
1068
+
1069
+ `create_session(...)`
1070
+ This operation creates a new portal session for a customer, returning a pre-authenticated URL that you can redirect them to.
1071
+
1072
+ **Synchronous**:
1073
+
1074
+ ```python
1075
+ session = client.portal.create_session(
1076
+ customerId="cust_789",
1077
+ )
1078
+ # Redirect your customer to the portal
1079
+ print(f"Portal URL: {session.customerPortalUrl}")
1080
+ ```
1081
+
1082
+ **Asynchronous**:
1083
+
1084
+ ```python
1085
+ session = await async_client.portal.create_session(
1086
+ customerId="cust_789",
1087
+ )
1088
+ # Redirect your customer to the portal
1089
+ print(f"Portal URL: {session.customerPortalUrl}")
1090
+ ```
1091
+
1092
+ ```json
1093
+ {
1094
+ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
1095
+ "email": "customer@example.com",
1096
+ "customerPortalUrl": "https://portal.kelviq.com/session/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
1097
+ }
1098
+ ```
1099
+
1100
+ **Required Parameters:**
1101
+
1102
+ * `customerId` (str): The unique identifier of the customer for whom the portal session is being created.
1103
+
1104
+ **Returns:**
1105
+
1106
+ An instance of `CreatePortalSessionResponse` (Pydantic model), which includes:
1107
+
1108
+ * `token` (str): The session token that authenticates the customer portal session.
1109
+ * `email` (str): The email address of the customer.
1110
+ * `customerPortalUrl` (str): The URL to redirect the customer to their customer portal. This link is pre-authenticated — no login required.
1111
+
1112
+ ---
1113
+ ## Webhooks
1114
+
1115
+ Kelviq can send real-time webhook notifications to your server when events occur in your account — for example, when a subscription is created or an invoice is paid.
1116
+
1117
+ ### Verifying webhook signatures
1118
+
1119
+ Every webhook request includes three headers that you must use to verify the request is genuinely from Kelviq:
1120
+
1121
+ | Header | Description |
1122
+ |---|---|
1123
+ | `webhook-id` | Unique identifier for the event |
1124
+ | `webhook-timestamp` | Unix timestamp of when the event was sent |
1125
+ | `webhook-signature` | HMAC-SHA256 signature, prefixed with `v1,` |
1126
+
1127
+ Use the `validate_event` helper to verify the signature and parse the event in one step. It raises `WebhookVerificationError` if the signature is invalid.
1128
+
1129
+ ```python
1130
+ from flask import Flask, request
1131
+ from kelviq_sdk import validate_event, WebhookVerificationError
1132
+
1133
+ app = Flask(__name__)
1134
+
1135
+ @app.route('/webhook', methods=['POST'])
1136
+ def webhook():
1137
+ try:
1138
+ event = validate_event(
1139
+ payload=request.data,
1140
+ headers=request.headers,
1141
+ secret='<YOUR_WEBHOOK_SECRET>',
1142
+ )
1143
+
1144
+ # Process the event
1145
+ print('Event type:', event.get('type'))
1146
+
1147
+ return "", 202
1148
+ except WebhookVerificationError as e:
1149
+ return "", 403
1150
+ ```
1151
+
1152
+ Always pass the **raw** request body (e.g. `request.data` in Flask) to `validate_event`. Parsing the body as JSON before verification will break the signature check.
1153
+
1154
+ ### Webhook event types
1155
+
1156
+ | Event | Description |
1157
+ |---|---|
1158
+ | `checkout.completed` | A checkout session was completed |
1159
+ | `customer.created` | A new customer was created |
1160
+ | `customer.updated` | A customer's details were updated |
1161
+ | `order.created` | A new order was placed |
1162
+ | `order.updated` | An order was updated |
1163
+ | `order.refunded` | An order was refunded |
1164
+ | `subscription.created` | A new subscription was created |
1165
+ | `subscription.updated` | A subscription was updated |
1166
+ | `subscription.cancelled` | A subscription was cancelled |
1167
+ | `subscription.plan_changed` | A subscription plan was changed |
1168
+ | `invoice.created` | A new invoice was created |
1169
+ | `invoice.paid` | An invoice was paid |
1170
+ | `refund.created` | A refund was initiated |
1171
+ | `refund.updated` | A refund status changed |
1172
+
1173
+ ### Best practices
1174
+
1175
+ * **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`.
1176
+ * **Use idempotency** — use the `webhook-id` header (or the event `id` field) to detect and skip duplicate deliveries.
1177
+ * **Validate every request** — always verify the signature before trusting the payload.
1178
+
1179
+ ---
1180
+ ## Using the Sandbox Environment
1181
+
1182
+ The SDK can connect to the Kelviq sandbox environment, which is perfect for **testing and development**. All operations performed in the sandbox are isolated and will not affect your live production data.
1183
+
1184
+ To use the sandbox, simply pass the argument `environment="sandbox"` when creating the client.
1185
+
1186
+ ### How to Create a Synchronous Client (Sandbox)
1187
+
1188
+ ```python
1189
+ from kelviq_sdk import Kelviq
1190
+
1191
+ # Note the 'environment' parameter
1192
+ client = Kelviq.create_sync_client(
1193
+ access_token=ACCESS_TOKEN,
1194
+ environment="sandbox"
1195
+ )
1196
+ ```
1197
+
1198
+ The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.