@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.
- package/README.md +34 -26
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- 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 +23 -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 +114 -34
- 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 +102 -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/server.js +10 -1
- package/dist/server.js.map +1 -1
- 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. [
|
|
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
|
-
|
|
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 `
|
|
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
|
-
|
|
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 |
|