@kelviq/mcp-server 0.4.0 → 1.0.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 (63) hide show
  1. package/README.md +34 -26
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +23 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +114 -34
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +102 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/server.js +10 -1
  62. package/dist/server.js.map +1 -1
  63. package/package.json +1 -1
@@ -60,6 +60,59 @@ from kelviq_sdk import Kelviq
60
60
  async_client = Kelviq.create_async_client(access_token=ACCESS_TOKEN)
61
61
  ```
62
62
 
63
+ ## Caching and offline resilience
64
+
65
+ Entitlement caching is enabled by default for both synchronous and asynchronous clients. The SDK keeps a per-process in-memory cache with a 60-second freshness window. Reads use a fresh memory entry first, then an optional distributed cache, and then the Entitlement API.
66
+
67
+ If the API is unreachable or returns a server error, the SDK returns the last known cached entitlement response when one exists. If the customer or feature has never been cached, the original request error is raised.
68
+
69
+ ```python
70
+ client = Kelviq.create_sync_client(
71
+ access_token=ACCESS_TOKEN,
72
+ enable_cache=True, # default: True
73
+ cache_ttl=60.0, # default: 60 seconds
74
+ )
75
+ ```
76
+
77
+ Set `enable_cache=False` to disable caching.
78
+
79
+ ### Share the cache across workers
80
+
81
+ 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.
82
+
83
+ ```shell
84
+ pip install "kelviq-sdk[redis]"
85
+ ```
86
+
87
+ ```python
88
+ from kelviq_sdk import Kelviq, RedisStore
89
+
90
+ store = RedisStore(
91
+ url="redis://localhost:6379/0",
92
+ prefix="kelviq:production",
93
+ )
94
+
95
+ client = Kelviq.create_sync_client(
96
+ access_token=ACCESS_TOKEN,
97
+ cache_store=store,
98
+ )
99
+ ```
100
+
101
+ For an asynchronous client, use `AsyncRedisStore`. Use the same prefix for every worker that should share state.
102
+
103
+ ### Replay queued usage
104
+
105
+ When a usage or event report fails because of a network problem, the SDK queues it and retries automatically on the next report call. You can also flush the queue explicitly:
106
+
107
+ ```python
108
+ remaining = client.reporting.flush()
109
+ # Async: remaining = await async_client.reporting.flush()
110
+ ```
111
+
112
+ `remaining` is the number of reports still queued. Without Redis, the queue exists only in the current process.
113
+
114
+ See [When the Entitlement API is unavailable](/product-catalog/entitlements#when-the-entitlement-api-is-unavailable) for access-control fallback guidance.
115
+
63
116
  #### Enum Helpers
64
117
 
65
118
  The SDK provides `ChargePeriod` and `CancellationType` enum classes to prevent typos when passing required string parameters:
@@ -86,9 +139,17 @@ The SDK currently supports the following operations:
86
139
 
87
140
  5. [Subscriptions](/backend-integration/python-sdk#subscriptions)
88
141
 
89
- 6. [License](/backend-integration/python-sdk#license)
142
+ 6. [Charges](/backend-integration/python-sdk#charges)
143
+
144
+ 7. [License](/backend-integration/python-sdk#license)
145
+
146
+ 8. [Portal](/backend-integration/python-sdk#portal)
147
+
148
+ 9. [Refunds](/backend-integration/python-sdk#refunds)
90
149
 
91
- 7. [Portal](/backend-integration/python-sdk#portal)
150
+ 10. [Payment Methods](/backend-integration/python-sdk#payment-methods)
151
+
152
+ 11. [Transactions](/backend-integration/python-sdk#transactions)
92
153
 
93
154
  ---
94
155
 
@@ -244,7 +305,8 @@ response = client.checkout.create_session(
244
305
  planIdentifier="plan-pro-monthly",
245
306
  chargePeriod="MONTHLY",
246
307
  customerId="cust_789", # Recommended, otherwise it will create a new customer
247
- successUrl="https://kelviq.com/checkout/success"
308
+ successUrl="https://kelviq.com/checkout/success",
309
+ trialPeriod=14,
248
310
  )
249
311
  print(f"Checkout Session URL: {response.checkoutUrl}")
250
312
  ```
@@ -292,6 +354,8 @@ print(f"Checkout Session URL: {response.checkoutUrl}")
292
354
 
293
355
  * `"DAILY"` / `ChargePeriod.DAILY`
294
356
 
357
+ * `"TWENTY_EIGHT_DAYS"` / `ChargePeriod.TWENTY_EIGHT_DAYS`
358
+
295
359
  * `"THREE_MONTHS"` / `ChargePeriod.THREE_MONTHS`
296
360
 
297
361
  * `"SIX_MONTHS"` / `ChargePeriod.SIX_MONTHS`
@@ -313,6 +377,8 @@ print(f"Checkout Session URL: {response.checkoutUrl}")
313
377
 
314
378
  * `ipAddress` (str): The IP Address of the customer, used for location based pricing.
315
379
 
380
+ * `trialPeriod` (int): Number of trial days to apply. Must be greater than or equal to `1` and overrides the selected plan's configured trial period.
381
+
316
382
  * `currencyCode` (str): The currency code for the checkout session (e.g. `"USD"`). Required when `customAmount` is provided.
317
383
 
318
384
  * `customAmount` (float): A custom amount to charge for this checkout session. When provided, `taxBehavior` and `currencyCode` are also required.
@@ -655,7 +721,7 @@ An instance of ReportUsageResponse (Pydantic model), which includes:
655
721
 
656
722
  ## Subscriptions
657
723
 
658
- The subscriptions module allows you to list, retrieve, create, update, and cancel customer subscriptions. You can access these operations via the `subscriptions` attribute on an initialized Kelviq client instance.
724
+ The subscriptions module allows you to list, retrieve, create, preview updates, update, and cancel customer subscriptions. You can access these operations via the `subscriptions` attribute on an initialized Kelviq client instance.
659
725
 
660
726
  ### List subscriptions
661
727
 
@@ -717,6 +783,8 @@ for subscription in page.results:
717
783
 
718
784
  * `page` (int): Page number to retrieve.
719
785
  * `page_size` (int): Number of subscriptions to return per page.
786
+ * `modifiedOnAfter` (str): Only return subscriptions modified on or after this ISO 8601 timestamp.
787
+ * `modifiedOnBefore` (str): Only return subscriptions modified on or before this ISO 8601 timestamp.
720
788
 
721
789
  **Returns:**
722
790
 
@@ -822,7 +890,7 @@ print(subscription.id, subscription.status)
822
890
  **Required Parameters:**
823
891
 
824
892
  * `planIdentifier` (str): Identifier of the plan to subscribe to.
825
- * `chargePeriod` (str | ChargePeriod): Billing period such as `MONTHLY`, `YEARLY`, `WEEKLY`, or `DAILY`.
893
+ * `chargePeriod` (str | ChargePeriod): Billing period such as `MONTHLY`, `YEARLY`, `WEEKLY`, `DAILY`, or `TWENTY_EIGHT_DAYS`.
826
894
  * `customerId` (str): Client-defined identifier of the customer.
827
895
 
828
896
  **Optional Parameters:**
@@ -840,12 +908,14 @@ A `CreateSubscriptionResponse` model containing the created subscription, includ
840
908
  **Synchronous**:
841
909
 
842
910
  ```python
843
- # Assuming 'client' is your synchronous Kelviq client
911
+ from kelviq_sdk import ProrationBehavior
912
+
844
913
  try:
845
914
  response = client.subscriptions.update(
846
915
  subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
847
916
  planIdentifier="premium-plan",
848
917
  chargePeriod="MONTHLY",
918
+ prorationBehavior=ProrationBehavior.PRORATE_NEXT_INVOICE,
849
919
  )
850
920
  print(response.subscriptionId)
851
921
  except Exception as e:
@@ -861,6 +931,7 @@ try:
861
931
  subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
862
932
  planIdentifier="new_plan_enterprise",
863
933
  chargePeriod="YEARLY",
934
+ prorationBehavior=ProrationBehavior.PRORATE_NEXT_INVOICE,
864
935
  offeringId="offer_abc",
865
936
  pricingTableId="pw_def",
866
937
  ruleId="rule_ghi",
@@ -890,6 +961,7 @@ except Exception as e:
890
961
  * `"YEARLY"` / `ChargePeriod.YEARLY`
891
962
  * `"WEEKLY"` / `ChargePeriod.WEEKLY`
892
963
  * `"DAILY"` / `ChargePeriod.DAILY`
964
+ * `"TWENTY_EIGHT_DAYS"` / `ChargePeriod.TWENTY_EIGHT_DAYS`
893
965
  * `"THREE_MONTHS"` / `ChargePeriod.THREE_MONTHS`
894
966
  * `"SIX_MONTHS"` / `ChargePeriod.SIX_MONTHS`
895
967
 
@@ -908,6 +980,7 @@ except Exception as e:
908
980
  * An ISO 8601 datetime string (e.g. `"2027-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.
909
981
  * If omitted, the existing trial behavior on the subscription is preserved.
910
982
  * `paymentBehavior` (`Literal["activate_on_payment"]`): Optional. Set to `"activate_on_payment"` to keep the current subscription active while payment is pending. The new plan and features are applied only after payment succeeds. If the pending update expires, the current subscription remains unchanged. Omit this field to use the default immediate-update behavior.
983
+ * `prorationBehavior` (`ProrationBehavior`): Controls how a mid-period change is billed. Use `ProrationBehavior.IMMEDIATE_CHARGE`, `ProrationBehavior.PRORATE_NEXT_INVOICE`, or `ProrationBehavior.NO_PRORATION`. When omitted, the organization's default is used.
911
984
 
912
985
  **Returns**:
913
986
 
@@ -915,6 +988,42 @@ An instance of `UpdateSubscriptionResponse`, which includes:
915
988
 
916
989
  * `subscriptionId` (str): UUID of the updated subscription.
917
990
 
991
+ ### Preview a subscription update
992
+
993
+ Calculates the financial effect of an update without changing the subscription, creating an invoice, or charging the customer.
994
+
995
+ **Synchronous:**
996
+
997
+ ```python
998
+ from kelviq_sdk import ProrationBehavior
999
+
1000
+ preview = client.subscriptions.preview_update(
1001
+ subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
1002
+ planIdentifier="premium-plan",
1003
+ chargePeriod="YEARLY",
1004
+ prorationBehavior=ProrationBehavior.PRORATE_NEXT_INVOICE,
1005
+ features=[{"identifier": "seats", "quantity": 10}],
1006
+ )
1007
+
1008
+ print(preview.recurringAmount, preview.amountChargedImmediately)
1009
+ print(preview.nextInvoice.lineItems if preview.nextInvoice else [])
1010
+ ```
1011
+
1012
+ **Asynchronous:**
1013
+
1014
+ ```python
1015
+ preview = await async_client.subscriptions.preview_update(
1016
+ subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
1017
+ planIdentifier="premium-plan",
1018
+ chargePeriod="YEARLY",
1019
+ prorationBehavior=ProrationBehavior.NO_PRORATION,
1020
+ )
1021
+ ```
1022
+
1023
+ Required parameters are `subscriptionId`, `planIdentifier`, and `chargePeriod`. Optional parameters are `prorationBehavior`, `features`, `ipAddress`, and `trialEnd`.
1024
+
1025
+ **Returns:** A `SubscriptionUpdatePreviewResponse` Pydantic model with recurring and immediate amounts in major and minor units, plus an optional next invoice and its line items.
1026
+
918
1027
  ### Cancel an active subscription for a customer.
919
1028
 
920
1029
  **Synchronous**:
@@ -972,6 +1081,305 @@ An instance of `CancelSubscriptionResponse`, which includes:
972
1081
 
973
1082
  ---
974
1083
 
1084
+ ## Charges
1085
+
1086
+ The synchronous and asynchronous `charges` clients immediately charge a customer's saved payment method for a one-time plan. Use sandbox mode when testing this operation.
1087
+
1088
+ **Synchronous:**
1089
+
1090
+ ```python
1091
+ charge = client.charges.create(
1092
+ planIdentifier="lifetime-access",
1093
+ chargePeriod="ONE_TIME",
1094
+ customerId="cust_789",
1095
+ currencyCode="USD",
1096
+ customAmount=49.99,
1097
+ taxBehavior="INCLUSIVE",
1098
+ features=[{"identifier": "seats", "quantity": 5}],
1099
+ )
1100
+
1101
+ print(charge.id, charge.status, charge.amount)
1102
+ ```
1103
+
1104
+ **Asynchronous:**
1105
+
1106
+ ```python
1107
+ charge = await async_client.charges.create(
1108
+ planIdentifier="lifetime-access",
1109
+ chargePeriod="ONE_TIME",
1110
+ customerId="cust_789",
1111
+ currencyCode="USD",
1112
+ customAmount=49.99,
1113
+ taxBehavior="EXCLUSIVE",
1114
+ )
1115
+ ```
1116
+
1117
+ `planIdentifier`, `chargePeriod="ONE_TIME"`, and `customerId` are required. `customAmount` must be positive and requires `currencyCode`. `taxBehavior` accepts `INCLUSIVE` or `EXCLUSIVE` and defaults to `EXCLUSIVE` on the API. Optional fields also include `features` and `ipAddress`.
1118
+
1119
+ **Returns:** A `CreateChargeResponse` Pydantic model containing the charge record, amount, currency, status, product, plan, features, and customer details.
1120
+
1121
+ ---
1122
+
1123
+ ## Refunds
1124
+
1125
+ The synchronous and asynchronous `refunds` clients let you list, create, and retrieve refunds for orders owned by your organization.
1126
+
1127
+ ### List refunds
1128
+
1129
+ **Synchronous:**
1130
+
1131
+ ```python
1132
+ page = client.refunds.list(
1133
+ status="SUCCEEDED",
1134
+ start_date="2026-07-01",
1135
+ page=1,
1136
+ page_size=10,
1137
+ )
1138
+ ```
1139
+
1140
+ **Asynchronous:**
1141
+
1142
+ ```python
1143
+ page = await async_client.refunds.list(status="SUCCEEDED", page=1, page_size=10)
1144
+ ```
1145
+
1146
+ ```json
1147
+ {
1148
+ "count": 1,
1149
+ "next": null,
1150
+ "previous": null,
1151
+ "results": [
1152
+ {
1153
+ "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
1154
+ "reason": "REQUESTED_BY_CUSTOMER",
1155
+ "amountUnits": 2500,
1156
+ "amount": 25,
1157
+ "internalNote": "Customer requested a partial refund.",
1158
+ "failureReason": null,
1159
+ "status": "SUCCEEDED",
1160
+ "order": { "id": "ORD-20260715123000-A1B2C" }
1161
+ }
1162
+ ]
1163
+ }
1164
+ ```
1165
+
1166
+ **Optional Parameters:**
1167
+
1168
+ * `search` : Search by refund ID, order ID, customer name, email, or ID.
1169
+ * `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`).
1172
+ * `page` : Page number to return.
1173
+ * `page_size` : Number of results per page. Defaults to 10, maximum 100.
1174
+
1175
+ **Returns:** A `RefundListResponse` Pydantic model with `count`, `next`, `previous`, and `results: List[RefundResponse]`.
1176
+
1177
+ ### Create a refund
1178
+
1179
+ **Synchronous:**
1180
+
1181
+ ```python
1182
+ refund = client.refunds.create(
1183
+ orderId="ORD-20260715123000-A1B2C",
1184
+ amountUnits=2500,
1185
+ reason="REQUESTED_BY_CUSTOMER",
1186
+ internalNote="Customer requested a partial refund.",
1187
+ )
1188
+ ```
1189
+
1190
+ **Asynchronous:**
1191
+
1192
+ ```python
1193
+ refund = await async_client.refunds.create(
1194
+ orderId="ORD-20260715123000-A1B2C",
1195
+ amountUnits=2500,
1196
+ )
1197
+ ```
1198
+
1199
+ ```json
1200
+ {
1201
+ "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
1202
+ "reason": "REQUESTED_BY_CUSTOMER",
1203
+ "amountUnits": 2500,
1204
+ "amount": 25,
1205
+ "internalNote": "Customer requested a partial refund.",
1206
+ "failureReason": null,
1207
+ "status": "SUCCEEDED",
1208
+ "order": { "id": "ORD-20260715123000-A1B2C" }
1209
+ }
1210
+ ```
1211
+
1212
+ **Required Parameters:**
1213
+
1214
+ * `orderId` : The ID of an order owned by your organization.
1215
+
1216
+ **Optional Parameters:**
1217
+
1218
+ * `amountUnits` : Amount to refund in the currency's minor unit (e.g. cents for USD). Takes precedence over `amount` when both are provided.
1219
+ * `amount` : Amount to refund in the currency's major unit (e.g. dollars for USD). Used only when `amountUnits` is omitted.
1220
+ * `reason` : One of `"DUPLICATE"`, `"FRAUDULENT"`, `"REQUESTED_BY_CUSTOMER"`, `"OTHER"`. Defaults to `"REQUESTED_BY_CUSTOMER"`.
1221
+ * `internalNote` : An internal note associated with the refund.
1222
+
1223
+ Omit both `amountUnits` and `amount` to refund the order's entire remaining refundable balance. The amount must be positive and cannot exceed the order's remaining refundable balance — the SDK raises `InvalidRequestError` if `orderId` is missing, and the API rejects invalid amounts.
1224
+
1225
+ **Returns:** A `RefundResponse` Pydantic model with `id`, `reason`, `amountUnits`, `amount`, `internalNote`, `failureReason`, `status`, and the complete serialized `order`.
1226
+
1227
+ ### Retrieve a refund
1228
+
1229
+ **Synchronous:**
1230
+
1231
+ ```python
1232
+ refund = client.refunds.retrieve("7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11")
1233
+ ```
1234
+
1235
+ **Asynchronous:**
1236
+
1237
+ ```python
1238
+ refund = await async_client.refunds.retrieve("7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11")
1239
+ ```
1240
+
1241
+ **Required Parameters:**
1242
+
1243
+ * `refundId` : The UUID of the refund.
1244
+
1245
+ **Returns:** A `RefundResponse` Pydantic model, as above.
1246
+
1247
+ ---
1248
+
1249
+ ## Payment Methods
1250
+
1251
+ The synchronous and asynchronous `payment_methods` clients list saved payment methods for your organization.
1252
+
1253
+ ### List payment methods
1254
+
1255
+ **Synchronous:**
1256
+
1257
+ ```python
1258
+ page = client.payment_methods.list(customer_id="geo-jacob", page_size=10)
1259
+ ```
1260
+
1261
+ **Asynchronous:**
1262
+
1263
+ ```python
1264
+ page = await async_client.payment_methods.list(customer_email="geojacob@example.com")
1265
+ ```
1266
+
1267
+ ```json
1268
+ {
1269
+ "count": 1,
1270
+ "next": null,
1271
+ "previous": null,
1272
+ "results": [
1273
+ {
1274
+ "id": 482,
1275
+ "customer": {
1276
+ "customerId": "geo-jacob",
1277
+ "name": "Geo Jacob",
1278
+ "email": "geojacob@example.com",
1279
+ "billingAddress": { "country": "US" }
1280
+ },
1281
+ "methodType": "card",
1282
+ "methodData": {
1283
+ "brand": "visa",
1284
+ "last4": "4242",
1285
+ "expMonth": 12,
1286
+ "expYear": 2029,
1287
+ "funding": "credit",
1288
+ "country": "US"
1289
+ },
1290
+ "isDefault": true,
1291
+ "status": "succeeded",
1292
+ "createdOn": "2026-04-02T06:12:04.123456Z",
1293
+ "modifiedOn": "2026-04-02T06:12:04.123456Z"
1294
+ }
1295
+ ]
1296
+ }
1297
+ ```
1298
+
1299
+ **Optional Parameters:**
1300
+
1301
+ * `customer_id` : Filter to payment methods belonging to the customer with this client-provided `customerId`.
1302
+ * `customer_email` : Filter to payment methods belonging to the customer with this email address.
1303
+ * `page` : Page number to return.
1304
+ * `page_size` : Number of results per page. Defaults to 10, maximum 100.
1305
+
1306
+ Only payment methods with status `"succeeded"` are included in results.
1307
+
1308
+ **Returns:** A `PaymentMethodListResponse` Pydantic model with `count`, `next`, `previous`, and `results: List[PaymentMethodResponse]`. Each `methodData` dict is payment-provider-specific; for `card` it includes `brand`, `last4`, `expMonth`, `expYear`, `funding`, and `country`.
1309
+
1310
+ ---
1311
+
1312
+ ## Transactions
1313
+
1314
+ The synchronous and asynchronous `transactions` clients list financial transactions for your organization, ordered newest first.
1315
+
1316
+ ### List transactions
1317
+
1318
+ **Synchronous:**
1319
+
1320
+ ```python
1321
+ page = client.transactions.list(
1322
+ status="success",
1323
+ start_date="2026-07-01",
1324
+ page=1,
1325
+ page_size=25,
1326
+ )
1327
+
1328
+ print(page.results[0].amountTotal, page.results[0].morFeeBreakdown)
1329
+ ```
1330
+
1331
+ **Asynchronous:**
1332
+
1333
+ ```python
1334
+ page = await async_client.transactions.list(status="success")
1335
+ ```
1336
+
1337
+ ```json
1338
+ {
1339
+ "count": 1,
1340
+ "next": null,
1341
+ "previous": null,
1342
+ "results": [
1343
+ {
1344
+ "id": "5b274952-0e54-48f6-aec6-e8a3f202b12e",
1345
+ "order": { "id": "ORD-20260715123000-A1B2C" },
1346
+ "createdOn": "2026-07-28T10:30:00Z",
1347
+ "currency": "USD",
1348
+ "currencySymbol": "$",
1349
+ "amountTotal": 100,
1350
+ "morFee": 4,
1351
+ "morFeeBreakdown": [
1352
+ { "name": "fixed_fee", "percentage": null, "valueUnits": 40, "currency": "USD" },
1353
+ { "name": "base_fee", "percentage": "2.9", "valueUnits": 290, "currency": "USD" },
1354
+ { "name": "subscription_fee", "percentage": "0.7", "valueUnits": 70, "currency": "USD" }
1355
+ ],
1356
+ "collectedTax": 0,
1357
+ "netPayout": 96,
1358
+ "status": "success",
1359
+ "transactionType": "CHARGE",
1360
+ "paymentMethodType": "card",
1361
+ "availableOn": "2026-08-04",
1362
+ "isSettled": false,
1363
+ "paymentMethodName": "visa",
1364
+ "last4": "4242"
1365
+ }
1366
+ ]
1367
+ }
1368
+ ```
1369
+
1370
+ **Optional Parameters:**
1371
+
1372
+ * `search` : Search by payment-provider IDs, customer name, email or ID, product name, or payment method type.
1373
+ * `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`).
1376
+ * `page` : Page number to return.
1377
+ * `page_size` : Number of results per page. Defaults to 10, maximum 100.
1378
+
1379
+ **Returns:** A `TransactionListResponse` Pydantic model with `count`, `next`, `previous`, and `results: List[TransactionResponse]`. Each transaction includes an itemized `morFeeBreakdown` (Merchant of Record fee components) when applicable — empty when no such fee applies.
1380
+
1381
+ ---
1382
+
975
1383
  ## License
976
1384
 
977
1385
  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.
@@ -1293,6 +1701,35 @@ An instance of `CreatePortalSessionResponse` (Pydantic model), which includes:
1293
1701
  * `email` (str): The email address of the customer.
1294
1702
  * `customerPortalUrl` (str): The customer's billing portal base URL. **This URL alone does not authenticate the session** — append the `token` as a query parameter (`{customerPortalUrl}?token={token}`) to produce the signed link you share with the customer. The token expires, so create a fresh session per visit.
1295
1703
 
1704
+ ### Deep-linking to add a payment method
1705
+
1706
+ You can send a customer directly to the **add payment method** form and have them redirected back to your application when they're done. Append these query parameters to the signed portal link, targeting the `billing` page:
1707
+
1708
+ | Parameter | Required | Description |
1709
+ |---|---|---|
1710
+ | `intent` | Yes | Set to `add_payment_method` to auto-open the add payment method form. |
1711
+ | `returnUrl` | No | URL-encoded `https` URL of your application. After the payment method is saved, the customer is redirected here with `?kelviq_setup=success` appended. `http` is only allowed for `localhost` during development. |
1712
+ | `customerId` | No | Opens the form for this specific customer account. If omitted, the customer's first account is used. |
1713
+
1714
+ ```python
1715
+ from urllib.parse import quote
1716
+
1717
+ session = client.portal.create_session(
1718
+ customerId="cust_789",
1719
+ )
1720
+
1721
+ return_url = quote("https://your-app.com/billing/done", safe="")
1722
+ add_payment_method_link = (
1723
+ f"{session.customerPortalUrl}billing"
1724
+ f"?token={session.token}"
1725
+ f"&intent=add_payment_method"
1726
+ f"&customerId=cust_789"
1727
+ f"&returnUrl={return_url}"
1728
+ )
1729
+ ```
1730
+
1731
+ After the customer saves their payment method, the portal redirects them to `https://your-app.com/billing/done?kelviq_setup=success`.
1732
+
1296
1733
  ---
1297
1734
  ## Webhooks
1298
1735
 
@@ -1349,6 +1786,7 @@ Always pass the **raw** request body (e.g. `request.data` in Flask) to `validate
1349
1786
  | `subscription.updated` | A subscription was updated |
1350
1787
  | `subscription.cancelled` | A subscription was cancelled |
1351
1788
  | `subscription.plan_changed` | A subscription plan was changed |
1789
+ | `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
1352
1790
  | `invoice.created` | A new invoice was created |
1353
1791
  | `invoice.paid` | An invoice was paid |
1354
1792
  | `refund.created` | A refund was initiated |