@kelviq/mcp-server 0.3.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.
- package/README.md +37 -30
- package/dist/config.d.ts +5 -0
- package/dist/config.js +31 -10
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +84 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +134 -63
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +109 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -0
- package/dist/schemas/kelviq.js +50 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +15 -3
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +3 -0
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +8 -0
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.js +1 -0
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +5 -0
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +5 -1
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- 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. [
|
|
127
|
+
6. [Charges](/backend-integration/node-sdk#charges)
|
|
76
128
|
|
|
77
|
-
7. [
|
|
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`):
|
|
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 |
|