@kelviq/mcp-server 0.4.0 → 1.1.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 (76) hide show
  1. package/README.md +43 -27
  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/README.md +16 -0
  6. package/dist/docs/backend-integration/better-auth.md +369 -0
  7. package/dist/docs/backend-integration/node-sdk.md +373 -5
  8. package/dist/docs/backend-integration/python-sdk.md +444 -6
  9. package/dist/docs/changelog/api.md +516 -5
  10. package/dist/docs/changelog/app.md +162 -0
  11. package/dist/docs/changelog/cli.md +33 -0
  12. package/dist/docs/changelog/mcp-server.md +23 -0
  13. package/dist/docs/changelog/node-sdk.md +124 -0
  14. package/dist/docs/changelog/python-sdk.md +135 -0
  15. package/dist/docs/changelog.md +3968 -0
  16. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  17. package/dist/docs/checkout/checkout-configuration.md +88 -22
  18. package/dist/docs/checkout/checkout-metadata.md +219 -0
  19. package/dist/docs/checkout/static-checkout-url.md +201 -0
  20. package/dist/docs/cli/commands.md +1 -1
  21. package/dist/docs/cli/environments.md +17 -9
  22. package/dist/docs/cli/kelviq-config.md +35 -1
  23. package/dist/docs/cli/overview.md +2 -0
  24. package/dist/docs/coustomers-management/overview.md +15 -19
  25. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  26. package/dist/docs/frontend-integration/react-ui.md +51 -16
  27. package/dist/docs/getstarted/fees.md +45 -54
  28. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  29. package/dist/docs/getstarted/review-process.md +3 -3
  30. package/dist/docs/guides/agent-toolkit.md +143 -0
  31. package/dist/docs/guides/mcp-server.md +138 -35
  32. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  33. package/dist/docs/guides/sandbox.md +34 -0
  34. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  35. package/dist/docs/guides/subscription-integration.md +28 -4
  36. package/dist/docs/guides/webhooks.md +367 -6
  37. package/dist/docs/manifest.json +98 -56
  38. package/dist/docs/openapi.json +7411 -2648
  39. package/dist/docs/payouts/overview.md +30 -0
  40. package/dist/docs/payouts/transactions.md +50 -6
  41. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  42. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  43. package/dist/docs/product-catalog/discounts.md +25 -12
  44. package/dist/docs/product-catalog/entitlements.md +53 -16
  45. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  46. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  47. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  48. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  49. package/dist/docs/product-catalog/plans.md +14 -0
  50. package/dist/docs/product-catalog/products.md +5 -13
  51. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  52. package/dist/docs/product-catalog/subscriptions.md +109 -12
  53. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  54. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  55. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  56. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  57. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  58. package/dist/http/client.js +9 -2
  59. package/dist/http/client.js.map +1 -1
  60. package/dist/http/errors.d.ts +8 -0
  61. package/dist/http/errors.js +20 -0
  62. package/dist/http/errors.js.map +1 -1
  63. package/dist/schemas/kelviq.d.ts +199 -0
  64. package/dist/schemas/kelviq.js +173 -0
  65. package/dist/schemas/kelviq.js.map +1 -1
  66. package/dist/server.js +11 -1
  67. package/dist/server.js.map +1 -1
  68. package/dist/tools/discounts.d.ts +3 -0
  69. package/dist/tools/discounts.js +74 -0
  70. package/dist/tools/discounts.js.map +1 -0
  71. package/dist/tools/index.js +4 -0
  72. package/dist/tools/index.js.map +1 -1
  73. package/dist/tools/webhooks.d.ts +10 -0
  74. package/dist/tools/webhooks.js +114 -0
  75. package/dist/tools/webhooks.js.map +1 -0
  76. package/package.json +1 -1
@@ -58,6 +58,58 @@ const client = new Kelviq({ accessToken: ACCESS_TOKEN });
58
58
 
59
59
  ```
60
60
 
61
+ ## Caching and offline resilience
62
+
63
+ Entitlement caching is enabled by default. The SDK keeps a per-process in-memory cache with a 60-second freshness window. Reads follow this order: fresh memory cache, optional distributed cache, then the Entitlement API. A successful API response refreshes both cache levels.
64
+
65
+ 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 thrown.
66
+
67
+ ```typescript
68
+ const client = new Kelviq({
69
+ accessToken: process.env.KELVIQ_SERVER_API_KEY,
70
+ enableCache: true, // default: true
71
+ cacheTtlMs: 60_000, // default: 60 seconds
72
+ });
73
+ ```
74
+
75
+ Set `enableCache: false` to disable caching.
76
+
77
+ ### Share the cache across instances
78
+
79
+ 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.
80
+
81
+ ```shell
82
+ npm install ioredis
83
+ ```
84
+
85
+ ```typescript
86
+ import { Kelviq, RedisStore } from '@kelviq/node-sdk';
87
+
88
+ const store = new RedisStore({
89
+ url: process.env.REDIS_URL,
90
+ prefix: 'kelviq:production',
91
+ });
92
+
93
+ const client = new Kelviq({
94
+ accessToken: process.env.KELVIQ_SERVER_API_KEY,
95
+ cacheStore: store,
96
+ });
97
+ ```
98
+
99
+ Use the same prefix for every instance that should share state.
100
+
101
+ ### Replay queued usage
102
+
103
+ 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:
104
+
105
+ ```typescript
106
+ const remaining = await client.reporting.flush();
107
+ ```
108
+
109
+ `remaining` is the number of reports still queued. Without Redis, the queue exists only in the current process.
110
+
111
+ See [When the Entitlement API is unavailable](/product-catalog/entitlements#when-the-entitlement-api-is-unavailable) for access-control fallback guidance.
112
+
61
113
  ## Supported Functionalities
62
114
 
63
115
  The SDK currently supports the following operations:
@@ -72,9 +124,17 @@ The SDK currently supports the following operations:
72
124
 
73
125
  5. [Subscriptions](/backend-integration/node-sdk#subscriptions)
74
126
 
75
- 6. [License](/backend-integration/node-sdk#license)
127
+ 6. [Charges](/backend-integration/node-sdk#charges)
76
128
 
77
- 7. [Portal](/backend-integration/node-sdk#portal)
129
+ 7. [License](/backend-integration/node-sdk#license)
130
+
131
+ 8. [Portal](/backend-integration/node-sdk#portal)
132
+
133
+ 9. [Refunds](/backend-integration/node-sdk#refunds)
134
+
135
+ 10. [Payment Methods](/backend-integration/node-sdk#payment-methods)
136
+
137
+ 11. [Transactions](/backend-integration/node-sdk#transactions)
78
138
 
79
139
  ---
80
140
 
@@ -200,6 +260,7 @@ const response = await client.checkout.createSession({
200
260
  chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
201
261
  successUrl: "https://yourwebsite.com/checkout/success",
202
262
  customerId: "cust_789", // Recommended, otherwise it will create a new customer
263
+ trialPeriod: 14,
203
264
  });
204
265
 
205
266
  ```
@@ -229,6 +290,8 @@ const response = await client.checkout.createSession({
229
290
 
230
291
  * `"DAILY"`
231
292
 
293
+ * `"TWENTY_EIGHT_DAYS"`
294
+
232
295
  * `"THREE_MONTHS"`
233
296
 
234
297
  * `"SIX_MONTHS"`
@@ -250,6 +313,8 @@ const response = await client.checkout.createSession({
250
313
 
251
314
  * `ipAddress` : The IP Address of the customer, used for location based pricing.
252
315
 
316
+ * `trialPeriod` : Number of trial days to apply. Must be an integer greater than or equal to `1` and overrides the selected plan's configured trial period.
317
+
253
318
  * `currencyCode` : The currency code for the checkout session (e.g. `"USD"`). Required when `customAmount` is provided.
254
319
 
255
320
  * `customAmount` : A custom amount to charge for this checkout session. When provided, `taxBehavior` and `currencyCode` are also required.
@@ -587,7 +652,7 @@ An instance of ReportUsageResponse (Object), which includes:
587
652
 
588
653
  ## Subscriptions
589
654
 
590
- 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.
655
+ 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.
591
656
 
592
657
  ### List subscriptions
593
658
 
@@ -635,6 +700,8 @@ for (const subscription of page.results) {
635
700
 
636
701
  * `page` (number): Page number to retrieve.
637
702
  * `pageSize` (number): Number of subscriptions to return per page.
703
+ * `modifiedOnAfter` (string): Only return subscriptions modified on or after this ISO 8601 timestamp.
704
+ * `modifiedOnBefore` (string): Only return subscriptions modified on or before this ISO 8601 timestamp.
638
705
 
639
706
  **Returns:**
640
707
 
@@ -710,7 +777,7 @@ console.log(subscription.id, subscription.status);
710
777
  **Required Parameters:**
711
778
 
712
779
  * `planIdentifier` (string): Identifier of the plan to subscribe to.
713
- * `chargePeriod` (`ChargePeriod`): Billing period such as `MONTHLY`, `YEARLY`, `WEEKLY`, or `DAILY`.
780
+ * `chargePeriod` (`ChargePeriod`): By default, organizations can use `MONTHLY`, `THREE_MONTHS`, `SIX_MONTHS`, `YEARLY`, and `ONE_TIME`. To enable `DAILY`, `WEEKLY`, or `TWENTY_EIGHT_DAYS`, contact [hi@kelviq.com](mailto:hi@kelviq.com).
714
781
  * `customerId` (string): Client-defined identifier of the customer.
715
782
 
716
783
  **Optional Parameters:**
@@ -726,13 +793,14 @@ A `CreateSubscriptionResponse` containing the created subscription, including it
726
793
  ### Updates an existing subscription to a new plan
727
794
 
728
795
  ```typescript
729
- import { CHARGE_PERIOD_CHOICES, PAYMENT_BEHAVIORS } from '@kelviq/node-sdk';
796
+ import { CHARGE_PERIOD_CHOICES, PAYMENT_BEHAVIORS, PRORATION_BEHAVIORS } from '@kelviq/node-sdk';
730
797
 
731
798
  try {
732
799
  const response = await client.subscriptions.update({
733
800
  subscriptionId: "sub_node_78058918",
734
801
  planIdentifier: "premium-plan-node",
735
802
  chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
803
+ prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
736
804
  trialEnd: "2027-12-31T23:59:59Z", // or "now" to end the trial immediately
737
805
  paymentBehavior: PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT
738
806
  });
@@ -757,6 +825,7 @@ try {
757
825
  * `"YEARLY"`
758
826
  * `"WEEKLY"`
759
827
  * `"DAILY"`
828
+ * `"TWENTY_EIGHT_DAYS"`
760
829
  * `"THREE_MONTHS"`
761
830
  * `"SIX_MONTHS"`
762
831
 
@@ -775,6 +844,7 @@ try {
775
844
  * An ISO 8601 datetime string (e.g. `"2027-12-31T23:59:59Z"`) to set a new trial end date. The datetime must be in the future. Naive datetimes (no timezone designator) are interpreted as UTC.
776
845
  * If omitted, the existing trial behavior on the subscription is preserved.
777
846
  * `paymentBehavior` (`PaymentBehavior`): Set to `PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT` (the value `"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.
847
+ * `prorationBehavior` (`ProrationBehavior`): Controls how a mid-period change is billed. Use `PRORATION_BEHAVIORS.IMMEDIATE_CHARGE`, `PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE`, or `PRORATION_BEHAVIORS.NO_PRORATION`. When omitted, the organization's default is used.
778
848
 
779
849
  The SDK validates `trialEnd` client-side — invalid datetime strings or past datetimes throw `InvalidRequestError` before the request is sent.
780
850
 
@@ -784,6 +854,29 @@ An instance of `UpdateSubscriptionResponse`, which includes:
784
854
 
785
855
  * `subscriptionId` (string): UUID of the updated subscription.
786
856
 
857
+ ### Preview a subscription update
858
+
859
+ Calculates the financial effect of an update without changing the subscription, creating an invoice, or charging the customer.
860
+
861
+ ```typescript
862
+ import { CHARGE_PERIOD_CHOICES, PRORATION_BEHAVIORS } from '@kelviq/node-sdk';
863
+
864
+ const preview = await client.subscriptions.previewUpdate({
865
+ subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
866
+ planIdentifier: "premium-plan",
867
+ chargePeriod: CHARGE_PERIOD_CHOICES.YEARLY,
868
+ prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
869
+ features: [{ identifier: "seats", quantity: 10 }],
870
+ });
871
+
872
+ console.log(preview.recurringAmount, preview.amountChargedImmediately);
873
+ console.log(preview.nextInvoice?.lineItems);
874
+ ```
875
+
876
+ Required parameters are `subscriptionId`, `planIdentifier`, and `chargePeriod`. Optional parameters are `prorationBehavior`, `features`, `ipAddress`, and `trialEnd`.
877
+
878
+ **Returns:** A `SubscriptionUpdatePreviewResponse` with recurring and immediate amounts in major and minor units, plus an optional next invoice and its line items.
879
+
787
880
  ### Cancel an active subscription for a customer.
788
881
 
789
882
  ```typescript
@@ -825,6 +918,252 @@ An instance of `CancelSubscriptionResponse`, which includes:
825
918
 
826
919
  ---
827
920
 
921
+ ## Charges
922
+
923
+ The `charges` module immediately charges a customer's saved payment method for a one-time plan. Use sandbox mode when testing this operation.
924
+
925
+ ```typescript
926
+ const charge = await client.charges.create({
927
+ planIdentifier: "lifetime-access",
928
+ chargePeriod: "ONE_TIME",
929
+ customerId: "cust_789",
930
+ currencyCode: "USD",
931
+ customAmount: 49.99,
932
+ taxBehavior: "INCLUSIVE",
933
+ features: [{ identifier: "seats", quantity: 5 }],
934
+ });
935
+
936
+ console.log(charge.id, charge.status, charge.amount);
937
+ ```
938
+
939
+ `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`.
940
+
941
+ **Returns:** A `CreateChargeResponse` containing the charge record, amount, currency, status, product, plan, features, and customer details.
942
+
943
+ ---
944
+
945
+ ## Refunds
946
+
947
+ The `refunds` module allows you to list, create, and retrieve refunds for orders owned by your organization. You can access these operations via the `refunds` attribute on an initialized `Kelviq` client instance.
948
+
949
+ ### List refunds
950
+
951
+ ```typescript
952
+ const page = await client.refunds.list({
953
+ status: "SUCCEEDED",
954
+ startDate: "2026-07-01",
955
+ page: 1,
956
+ pageSize: 10,
957
+ });
958
+ ```
959
+
960
+ ```json
961
+ {
962
+ "count": 1,
963
+ "next": null,
964
+ "previous": null,
965
+ "results": [
966
+ {
967
+ "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
968
+ "reason": "REQUESTED_BY_CUSTOMER",
969
+ "amountUnits": 2500,
970
+ "amount": 25,
971
+ "internalNote": "Customer requested a partial refund.",
972
+ "failureReason": null,
973
+ "status": "SUCCEEDED",
974
+ "order": { "id": "ORD-20260715123000-A1B2C" }
975
+ }
976
+ ]
977
+ }
978
+ ```
979
+
980
+ **Optional Parameters:**
981
+
982
+ * `search` : Search by refund ID, order ID, customer name, email, or ID.
983
+ * `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`).
986
+ * `page` : Page number to return.
987
+ * `pageSize` : Number of results per page. Defaults to 10, maximum 100.
988
+
989
+ **Returns:** A `RefundListResponse` (TypeScript Interface) with `count`, `next`, `previous`, and `results: RefundResponse[]`.
990
+
991
+ ### Create a refund
992
+
993
+ ```typescript
994
+ const refund = await client.refunds.create({
995
+ orderId: "ORD-20260715123000-A1B2C",
996
+ amountUnits: 2500,
997
+ reason: "REQUESTED_BY_CUSTOMER",
998
+ internalNote: "Customer requested a partial refund.",
999
+ });
1000
+ ```
1001
+
1002
+ ```json
1003
+ {
1004
+ "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
1005
+ "reason": "REQUESTED_BY_CUSTOMER",
1006
+ "amountUnits": 2500,
1007
+ "amount": 25,
1008
+ "internalNote": "Customer requested a partial refund.",
1009
+ "failureReason": null,
1010
+ "status": "SUCCEEDED",
1011
+ "order": { "id": "ORD-20260715123000-A1B2C" }
1012
+ }
1013
+ ```
1014
+
1015
+ **Required Parameters:**
1016
+
1017
+ * `orderId` : The ID of an order owned by your organization.
1018
+
1019
+ **Optional Parameters:**
1020
+
1021
+ * `amountUnits` : Amount to refund in the currency's minor unit (e.g. cents for USD). Takes precedence over `amount` when both are provided.
1022
+ * `amount` : Amount to refund in the currency's major unit (e.g. dollars for USD). Used only when `amountUnits` is omitted.
1023
+ * `reason` : One of `"DUPLICATE"`, `"FRAUDULENT"`, `"REQUESTED_BY_CUSTOMER"`, `"OTHER"`. Defaults to `"REQUESTED_BY_CUSTOMER"`.
1024
+ * `internalNote` : An internal note associated with the refund.
1025
+
1026
+ 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 throws `InvalidRequestError` if `orderId` is missing, and the API rejects invalid amounts.
1027
+
1028
+ **Returns:** A `RefundResponse` (TypeScript Interface) with `id`, `reason`, `amountUnits`, `amount`, `internalNote`, `failureReason`, `status`, and the complete serialized `order`.
1029
+
1030
+ ### Retrieve a refund
1031
+
1032
+ ```typescript
1033
+ const refund = await client.refunds.retrieve({
1034
+ refundId: "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
1035
+ });
1036
+ ```
1037
+
1038
+ **Required Parameters:**
1039
+
1040
+ * `refundId` : The UUID of the refund.
1041
+
1042
+ **Returns:** A `RefundResponse` (TypeScript Interface), as above.
1043
+
1044
+ ---
1045
+
1046
+ ## Payment Methods
1047
+
1048
+ The `paymentMethods` module lists saved payment methods for your organization. You can access this operation via the `paymentMethods` attribute on an initialized `Kelviq` client instance.
1049
+
1050
+ ### List payment methods
1051
+
1052
+ ```typescript
1053
+ const page = await client.paymentMethods.list({
1054
+ customerId: "geo-jacob",
1055
+ pageSize: 10,
1056
+ });
1057
+ ```
1058
+
1059
+ ```json
1060
+ {
1061
+ "count": 1,
1062
+ "next": null,
1063
+ "previous": null,
1064
+ "results": [
1065
+ {
1066
+ "id": 482,
1067
+ "customer": {
1068
+ "customerId": "geo-jacob",
1069
+ "name": "Geo Jacob",
1070
+ "email": "geojacob@example.com",
1071
+ "billingAddress": { "country": "US" }
1072
+ },
1073
+ "methodType": "card",
1074
+ "methodData": {
1075
+ "brand": "visa",
1076
+ "last4": "4242",
1077
+ "expMonth": 12,
1078
+ "expYear": 2029,
1079
+ "funding": "credit",
1080
+ "country": "US"
1081
+ },
1082
+ "isDefault": true,
1083
+ "status": "succeeded",
1084
+ "createdOn": "2026-04-02T06:12:04.123456Z",
1085
+ "modifiedOn": "2026-04-02T06:12:04.123456Z"
1086
+ }
1087
+ ]
1088
+ }
1089
+ ```
1090
+
1091
+ **Optional Parameters:**
1092
+
1093
+ * `customerId` : Filter to payment methods belonging to the customer with this client-provided `customerId`.
1094
+ * `customerEmail` : Filter to payment methods belonging to the customer with this email address.
1095
+ * `page` : Page number to return.
1096
+ * `pageSize` : Number of results per page. Defaults to 10, maximum 100.
1097
+
1098
+ Only payment methods with status `"succeeded"` are included in results.
1099
+
1100
+ **Returns:** A `PaymentMethodListResponse` (TypeScript Interface) with `count`, `next`, `previous`, and `results: PaymentMethodResponse[]`. Each `methodData` object is payment-provider-specific; for `card` it includes `brand`, `last4`, `expMonth`, `expYear`, `funding`, and `country`.
1101
+
1102
+ ---
1103
+
1104
+ ## Transactions
1105
+
1106
+ The `transactions` module lists financial transactions for your organization, ordered newest first. You can access this operation via the `transactions` attribute on an initialized `Kelviq` client instance.
1107
+
1108
+ ### List transactions
1109
+
1110
+ ```typescript
1111
+ const page = await client.transactions.list({
1112
+ status: "success",
1113
+ startDate: "2026-07-01",
1114
+ page: 1,
1115
+ pageSize: 25,
1116
+ });
1117
+
1118
+ console.log(page.results[0].amountTotal, page.results[0].morFeeBreakdown);
1119
+ ```
1120
+
1121
+ ```json
1122
+ {
1123
+ "count": 1,
1124
+ "next": null,
1125
+ "previous": null,
1126
+ "results": [
1127
+ {
1128
+ "id": "5b274952-0e54-48f6-aec6-e8a3f202b12e",
1129
+ "order": { "id": "ORD-20260715123000-A1B2C" },
1130
+ "createdOn": "2026-07-28T10:30:00Z",
1131
+ "currency": "USD",
1132
+ "currencySymbol": "$",
1133
+ "amountTotal": 100,
1134
+ "morFee": 4,
1135
+ "morFeeBreakdown": [
1136
+ { "name": "fixed_fee", "percentage": null, "valueUnits": 40, "currency": "USD" },
1137
+ { "name": "base_fee", "percentage": "2.9", "valueUnits": 290, "currency": "USD" },
1138
+ { "name": "subscription_fee", "percentage": "0.7", "valueUnits": 70, "currency": "USD" }
1139
+ ],
1140
+ "collectedTax": 0,
1141
+ "netPayout": 96,
1142
+ "status": "success",
1143
+ "transactionType": "CHARGE",
1144
+ "paymentMethodType": "card",
1145
+ "availableOn": "2026-08-04",
1146
+ "isSettled": false,
1147
+ "paymentMethodName": "visa",
1148
+ "last4": "4242"
1149
+ }
1150
+ ]
1151
+ }
1152
+ ```
1153
+
1154
+ **Optional Parameters:**
1155
+
1156
+ * `search` : Search by payment-provider IDs, customer name, email or ID, product name, or payment method type.
1157
+ * `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`).
1160
+ * `page` : Page number to return.
1161
+ * `pageSize` : Number of results per page. Defaults to 10, maximum 100.
1162
+
1163
+ **Returns:** A `TransactionListResponse` (TypeScript Interface) with `count`, `next`, `previous`, and `results: TransactionResponse[]`. Each transaction includes an itemized `morFeeBreakdown` (Merchant of Record fee components) when applicable — empty when no such fee applies.
1164
+
1165
+ ---
1166
+
828
1167
  ## License
829
1168
 
830
1169
  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.
@@ -1093,6 +1432,34 @@ An instance of `CreatePortalSessionResponse` (TypeScript Interface), which inclu
1093
1432
  * `email` : The email address of the customer.
1094
1433
  * `customerPortalUrl` : 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.
1095
1434
 
1435
+ ### Deep-linking to add a payment method
1436
+
1437
+ 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:
1438
+
1439
+ | Parameter | Required | Description |
1440
+ |---|---|---|
1441
+ | `intent` | Yes | Set to `add_payment_method` to auto-open the add payment method form. |
1442
+ | `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. |
1443
+ | `customerId` | No | Opens the form for this specific customer account. If omitted, the customer's first account is used. |
1444
+
1445
+ ```typescript
1446
+ const session = await client.portal.createSession({
1447
+ customerId: "cust_789",
1448
+ });
1449
+
1450
+ const returnUrl = encodeURIComponent("https://your-app.com/billing/done");
1451
+ const addPaymentMethodLink =
1452
+ `${session.customerPortalUrl}billing` +
1453
+ `?token=${session.token}` +
1454
+ `&intent=add_payment_method` +
1455
+ `&customerId=cust_789` +
1456
+ `&returnUrl=${returnUrl}`;
1457
+
1458
+ res.redirect(addPaymentMethodLink);
1459
+ ```
1460
+
1461
+ After the customer saves their payment method, the portal redirects them to `https://your-app.com/billing/done?kelviq_setup=success`.
1462
+
1096
1463
  ---
1097
1464
  ## Webhooks
1098
1465
 
@@ -1153,6 +1520,7 @@ Use `express.raw()` (not `express.json()`) so that the raw request body is prese
1153
1520
  | `subscription.updated` | A subscription was updated |
1154
1521
  | `subscription.cancelled` | A subscription was cancelled |
1155
1522
  | `subscription.plan_changed` | A subscription plan was changed |
1523
+ | `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
1156
1524
  | `invoice.created` | A new invoice was created |
1157
1525
  | `invoice.paid` | An invoice was paid |
1158
1526
  | `refund.created` | A refund was initiated |