@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
|
@@ -29,6 +29,23 @@ Your signing secret is shown only once. If you lose it, you must regenerate it f
|
|
|
29
29
|
|
|
30
30
|
---
|
|
31
31
|
|
|
32
|
+
## Inspect and resend deliveries
|
|
33
|
+
|
|
34
|
+
Open **Settings → Webhooks** and select an endpoint to view its delivery logs. Each delivery shows the event type, status, response code, and response body.
|
|
35
|
+
|
|
36
|
+
To retry a delivery:
|
|
37
|
+
|
|
38
|
+
1. Fix the endpoint or deployment issue that caused the delivery to fail.
|
|
39
|
+
2. Open the failed delivery in the webhook logs.
|
|
40
|
+
3. Click **Resend**.
|
|
41
|
+
4. Review the new delivery attempt and its response.
|
|
42
|
+
|
|
43
|
+
Kelviq also retries failed deliveries automatically. A manual resend is useful when the endpoint is working again and you want to retry immediately.
|
|
44
|
+
|
|
45
|
+
Automatic retries and manual resends can deliver the same event more than once. Process webhooks idempotently using the event `id` or the `webhook-id` header.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
32
49
|
## Event Types
|
|
33
50
|
|
|
34
51
|
| Event | Description |
|
|
@@ -40,14 +57,82 @@ Your signing secret is shown only once. If you lose it, you must regenerate it f
|
|
|
40
57
|
| `order.updated` | An existing order was updated. |
|
|
41
58
|
| `order.refunded` | A full or partial refund was issued against an order. |
|
|
42
59
|
| `subscription.created` | A new subscription was activated for a customer. |
|
|
43
|
-
| `subscription.updated` | A subscription's details were modified. |
|
|
44
|
-
| `subscription.cancelled` | A subscription
|
|
60
|
+
| `subscription.updated` | A subscription's details were modified — including when a cancellation is scheduled for the end of the current period (status stays active; `end_date` is set). |
|
|
61
|
+
| `subscription.cancelled` | A subscription actually reached cancelled status. For a period-end cancellation, this fires later, when the period ends — not at the moment it was scheduled. |
|
|
45
62
|
| `subscription.plan_changed` | A subscription was moved to a different plan. |
|
|
63
|
+
| `subscription.trial_will_end` | A subscription's trial period is ending soon. |
|
|
46
64
|
| `feature.usage_alert` | A customer's feature usage crossed a configured threshold. |
|
|
47
65
|
| `invoice.created` | A new invoice was generated. |
|
|
48
66
|
| `invoice.paid` | An invoice was paid and funds were collected. |
|
|
67
|
+
| `invoice.payment_failed` | A subscription invoice payment failed or requires customer action. |
|
|
49
68
|
| `refund.created` | A refund was initiated. |
|
|
50
69
|
| `refund.updated` | A refund's status changed (e.g., from pending to completed). |
|
|
70
|
+
| `payment_method.created` | A new payment method was added for a customer. |
|
|
71
|
+
| `payment_method.updated` | A payment method's status or default state changed. |
|
|
72
|
+
| `payment_method.deleted` | A payment method was removed from a customer. |
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Checkout, subscription, and payment lifecycle
|
|
77
|
+
|
|
78
|
+
### Checkout and subscription creation
|
|
79
|
+
|
|
80
|
+
`checkout.completed` confirms that checkout finished successfully, but it does not include `subscription_id`. Kelviq creates the subscription after checkout and sends its ID in `subscription.created`.
|
|
81
|
+
|
|
82
|
+
Use your customer identifier or checkout `metadata` to correlate the two events. See [Add metadata to checkout](/checkout/checkout-metadata) for request and webhook examples. Do not treat the checkout redirect as proof that a subscription has been created.
|
|
83
|
+
|
|
84
|
+
### Successful invoice payments
|
|
85
|
+
|
|
86
|
+
Kelviq sends `invoice.paid` whenever an invoice is paid, including invoices that are created directly with a `PAID` status. Use this event for payment-driven work such as recording revenue, starting an asynchronous provisioning job, or notifying an internal system.
|
|
87
|
+
|
|
88
|
+
For request-time access checks, query the customer's current entitlements instead of relying on a local webhook-derived subscription state.
|
|
89
|
+
|
|
90
|
+
### Failed invoice payments
|
|
91
|
+
|
|
92
|
+
Kelviq sends `invoice.payment_failed` when a subscription invoice payment fails or requires customer action. Use `data.object.subscription_id` and the embedded `customer` to identify the affected account. The invoice `status` is `PAYMENT_FAILED` for a failed attempt and can remain `OPEN` when the payment requires customer action.
|
|
93
|
+
|
|
94
|
+
This event can be followed by `invoice.paid` if the customer completes authentication or a later retry succeeds. Handle both events idempotently and treat the latest invoice and subscription state as authoritative.
|
|
95
|
+
|
|
96
|
+
### Subscription end dates
|
|
97
|
+
|
|
98
|
+
Subscription webhook objects include `end_date` inside `data.object`. Kelviq sets the field when a subscription has been cancelled or is scheduled to cancel on a future date. Otherwise, the value is `null`.
|
|
99
|
+
|
|
100
|
+
Use `end_date` for the subscription's scheduled or final end. `billing_period_end_time` describes the current billing period instead and should not be treated as the subscription's cancellation date.
|
|
101
|
+
|
|
102
|
+
### Failed renewal payments
|
|
103
|
+
|
|
104
|
+
Kelviq does not currently send a separate `payment.failed` event. For a failed card renewal:
|
|
105
|
+
|
|
106
|
+
1. The subscription moves to `past_due`.
|
|
107
|
+
2. Kelviq emails the customer a payment link.
|
|
108
|
+
3. Kelviq sends `subscription.updated` with the new subscription state.
|
|
109
|
+
4. Kelviq retries collection up to eight times over 14 days.
|
|
110
|
+
5. If all recovery attempts fail, Kelviq cancels the subscription and sends `subscription.cancelled`.
|
|
111
|
+
|
|
112
|
+
Do not remove access when you receive the first `subscription.updated` with `past_due` unless that is your own policy. Use the final subscription status or a live entitlement check to decide when access should end.
|
|
113
|
+
|
|
114
|
+
The retry window applies only to card payments. Kelviq does not retry a failed non-card renewal; the subscription is cancelled after the failure.
|
|
115
|
+
|
|
116
|
+
### Billing period field names
|
|
117
|
+
|
|
118
|
+
Subscription payloads use `billing_period_start_time` and `billing_period_end_time`. Match these names exactly when parsing dates. They describe the current billing period; use `end_date` for the subscription's scheduled or final end.
|
|
119
|
+
|
|
120
|
+
### Plan changes
|
|
121
|
+
|
|
122
|
+
By default, Kelviq applies a plan change immediately, charges any prorated difference, and sends `subscription.plan_changed`. After the generated invoice is paid, Kelviq sends the related order and invoice events.
|
|
123
|
+
|
|
124
|
+
If you update a subscription with `paymentBehavior: "activate_on_payment"`, the existing subscription remains `active` while payment is pending. A payment method that requires customer action leaves the updated subscription in `incomplete`. After payment succeeds, the updated subscription becomes `active` and the previous subscription becomes `superseded`. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes `incomplete_expired` and the existing subscription remains active.
|
|
125
|
+
|
|
126
|
+
Do not provision the new plan from the update API response alone. Read the latest subscription status or query the customer's current entitlements before changing access.
|
|
127
|
+
|
|
128
|
+
### Partial and full refunds
|
|
129
|
+
|
|
130
|
+
`order.refunded` identifies whether the order is partially or fully refunded through its `status`:
|
|
131
|
+
|
|
132
|
+
* `PARTIAL_REFUND` for a partial refund
|
|
133
|
+
* `REFUNDED` for a full refund
|
|
134
|
+
|
|
135
|
+
The `order.refunded` payload does not include the refunded amount. Read `amount` or `amount_units` from `refund.created` and `refund.updated` when you need the exact value.
|
|
51
136
|
|
|
52
137
|
---
|
|
53
138
|
|
|
@@ -384,6 +469,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
384
469
|
"end_date": null,
|
|
385
470
|
"billing_period_start_time": "2026-03-11T05:25:33Z",
|
|
386
471
|
"billing_period_end_time": "2026-04-10T06:28:58Z",
|
|
472
|
+
"trial_start": "2026-03-11T05:25:33Z",
|
|
473
|
+
"trial_end": "2026-03-25T05:25:33Z",
|
|
387
474
|
"customer": {
|
|
388
475
|
"id": "1bb69d0f-39f8-4db8-aace-e003d6e5f3ed",
|
|
389
476
|
"name": "Geo Jacob",
|
|
@@ -450,6 +537,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
450
537
|
},
|
|
451
538
|
"billing_period_start_time": "2026-04-02T05:04:43Z",
|
|
452
539
|
"billing_period_end_time": "2026-05-02T05:04:43Z",
|
|
540
|
+
"trial_start": "2026-04-02T05:04:43Z",
|
|
541
|
+
"trial_end": "2026-04-16T05:04:43Z",
|
|
453
542
|
"created_on": "2026-04-02T05:21:28Z",
|
|
454
543
|
"modified_on": "2026-04-02T05:21:33Z"
|
|
455
544
|
},
|
|
@@ -504,6 +593,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
504
593
|
},
|
|
505
594
|
"billing_period_start_time": "2026-04-02T04:25:13Z",
|
|
506
595
|
"billing_period_end_time": "2026-05-02T04:25:13Z",
|
|
596
|
+
"trial_start": "2026-04-02T04:25:13Z",
|
|
597
|
+
"trial_end": "2026-04-16T04:25:13Z",
|
|
507
598
|
"created_on": "2026-04-02T04:25:20Z",
|
|
508
599
|
"modified_on": "2026-04-02T05:02:47Z"
|
|
509
600
|
},
|
|
@@ -541,6 +632,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
541
632
|
"end_date": null,
|
|
542
633
|
"billing_period_start_time": "2026-02-26T05:25:11Z",
|
|
543
634
|
"billing_period_end_time": "2026-03-26T05:25:11Z",
|
|
635
|
+
"trial_start": "2026-02-26T05:25:11Z",
|
|
636
|
+
"trial_end": "2026-03-12T05:25:11Z",
|
|
544
637
|
"customer": {
|
|
545
638
|
"id": "798e663f-2fe9-43d7-879f-2549263e20d1",
|
|
546
639
|
"name": "Geo",
|
|
@@ -574,6 +667,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
574
667
|
"end_date": null,
|
|
575
668
|
"billing_period_start_time": "2026-02-26T05:25:11Z",
|
|
576
669
|
"billing_period_end_time": "2026-03-26T05:25:11Z",
|
|
670
|
+
"trial_start": "2026-02-26T05:25:11Z",
|
|
671
|
+
"trial_end": "2026-03-12T05:25:11Z",
|
|
577
672
|
"customer": {
|
|
578
673
|
"id": "798e663f-2fe9-43d7-879f-2549263e20d1",
|
|
579
674
|
"name": "Geo",
|
|
@@ -590,6 +685,60 @@ The request body is a JSON object with the following top-level fields:
|
|
|
590
685
|
}
|
|
591
686
|
```
|
|
592
687
|
|
|
688
|
+
```json
|
|
689
|
+
{
|
|
690
|
+
"id": "7c6d5e4f-3b2a-4190-8e7d-6c5b4a3f2e1d",
|
|
691
|
+
"type": "subscription.trial_will_end",
|
|
692
|
+
"created_at": "2026-08-08T05:25:34Z",
|
|
693
|
+
"data": {
|
|
694
|
+
"object": {
|
|
695
|
+
"id": "a22f1b2a-b922-4a28-9b0e-75e826988b4b",
|
|
696
|
+
"object": "subscription",
|
|
697
|
+
"status": "trialing",
|
|
698
|
+
"plan": {
|
|
699
|
+
"name": "default pd",
|
|
700
|
+
"version": 1,
|
|
701
|
+
"identifier": "default-pd"
|
|
702
|
+
},
|
|
703
|
+
"product": {
|
|
704
|
+
"id": "b4ea7e75-5dbe-4b3b-96e0-9a31dfe5a600",
|
|
705
|
+
"name": "Migrate PD"
|
|
706
|
+
},
|
|
707
|
+
"amount": "21.24",
|
|
708
|
+
"amount_units": 2100,
|
|
709
|
+
"currency": "USD",
|
|
710
|
+
"recurrence": "1 month",
|
|
711
|
+
"start_date": "2026-08-01",
|
|
712
|
+
"end_date": null,
|
|
713
|
+
"billing_period_start_time": "2026-08-01T05:25:33Z",
|
|
714
|
+
"billing_period_end_time": "2026-08-31T05:25:33Z",
|
|
715
|
+
"trial_start": "2026-08-01T05:25:33Z",
|
|
716
|
+
"trial_end": "2026-08-11T05:25:33Z",
|
|
717
|
+
"customer": {
|
|
718
|
+
"id": "1bb69d0f-39f8-4db8-aace-e003d6e5f3ed",
|
|
719
|
+
"name": "Geo Jacob",
|
|
720
|
+
"email": "geo@example.com",
|
|
721
|
+
"customer_id": "1",
|
|
722
|
+
"billing_address": {
|
|
723
|
+
"city": "Bangalore",
|
|
724
|
+
"line1": null,
|
|
725
|
+
"line2": null,
|
|
726
|
+
"state": "Karnataka",
|
|
727
|
+
"country": "IN",
|
|
728
|
+
"postal_code": "560001"
|
|
729
|
+
}
|
|
730
|
+
},
|
|
731
|
+
"features": null,
|
|
732
|
+
"organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c",
|
|
733
|
+
"created_on": "2026-08-01T05:25:34Z",
|
|
734
|
+
"modified_on": "2026-08-01T05:25:34Z"
|
|
735
|
+
}
|
|
736
|
+
}
|
|
737
|
+
}
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
`data.object` uses the same subscription payload shape as `subscription.created`/`subscription.updated`; the trial's remaining time is in `trial_end`. Kelviq sends this once, a few days before `trial_end`, mirroring Stripe's own `customer.subscription.trial_will_end` timing — it's skipped if the subscription has already converted to `active` or has no trial days left by the time Stripe's notice arrives.
|
|
741
|
+
|
|
593
742
|
```json
|
|
594
743
|
{
|
|
595
744
|
"id": "575a1aa4-3414-4e08-b4ad-6bfd3e96322d",
|
|
@@ -649,6 +798,10 @@ The request body is a JSON object with the following top-level fields:
|
|
|
649
798
|
"amount_total_units": 4000,
|
|
650
799
|
"currency": "USD",
|
|
651
800
|
"due_date": null,
|
|
801
|
+
"attempt_count": 0,
|
|
802
|
+
"next_payment_attempt": null,
|
|
803
|
+
"failure_details": null,
|
|
804
|
+
"payment_link": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
|
|
652
805
|
"order_id": null,
|
|
653
806
|
"customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
654
807
|
"customer": {
|
|
@@ -693,6 +846,10 @@ The request body is a JSON object with the following top-level fields:
|
|
|
693
846
|
"amount_total_units": 4000,
|
|
694
847
|
"currency": "USD",
|
|
695
848
|
"due_date": null,
|
|
849
|
+
"attempt_count": 1,
|
|
850
|
+
"next_payment_attempt": null,
|
|
851
|
+
"failure_details": null,
|
|
852
|
+
"payment_link": null,
|
|
696
853
|
"order_id": null,
|
|
697
854
|
"customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
698
855
|
"customer": {
|
|
@@ -726,6 +883,60 @@ The request body is a JSON object with the following top-level fields:
|
|
|
726
883
|
}
|
|
727
884
|
```
|
|
728
885
|
|
|
886
|
+
```json
|
|
887
|
+
{
|
|
888
|
+
"id": "1b8b128e-31c8-48b2-9d0b-f477ce543d58",
|
|
889
|
+
"type": "invoice.payment_failed",
|
|
890
|
+
"created_at": "2026-08-01T10:14:22Z",
|
|
891
|
+
"data": {
|
|
892
|
+
"object": {
|
|
893
|
+
"id": "INV-20260801101420-Q7M2P",
|
|
894
|
+
"object": "invoice",
|
|
895
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
896
|
+
"status": "PAYMENT_FAILED",
|
|
897
|
+
"customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
898
|
+
"customer": {
|
|
899
|
+
"id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
900
|
+
"name": "Geo Jacob",
|
|
901
|
+
"email": "geojacob@example.com",
|
|
902
|
+
"customer_id": "geo-jacob",
|
|
903
|
+
"billing_address": {
|
|
904
|
+
"line1": null,
|
|
905
|
+
"line2": null,
|
|
906
|
+
"city": null,
|
|
907
|
+
"state": null,
|
|
908
|
+
"postal_code": "680121",
|
|
909
|
+
"country": "IN"
|
|
910
|
+
}
|
|
911
|
+
},
|
|
912
|
+
"product": {
|
|
913
|
+
"id": "df398021-477b-4e67-972d-c763a2f2ba7b",
|
|
914
|
+
"name": "ParityDeals"
|
|
915
|
+
},
|
|
916
|
+
"subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
|
|
917
|
+
"order_id": null,
|
|
918
|
+
"payment_link": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
|
|
919
|
+
"amount_total": "40",
|
|
920
|
+
"amount_total_units": 4000,
|
|
921
|
+
"currency": "USD",
|
|
922
|
+
"paid_at": null,
|
|
923
|
+
"due_date": "2026-08-01T10:14:22Z",
|
|
924
|
+
"attempt_count": 1,
|
|
925
|
+
"next_payment_attempt": "2026-08-04T10:14:22Z",
|
|
926
|
+
"failure_details": {
|
|
927
|
+
"code": "card_declined",
|
|
928
|
+
"message": "Your card was declined.",
|
|
929
|
+
"payment_method_type": "card"
|
|
930
|
+
},
|
|
931
|
+
"created_on": "2026-08-01T10:14:20Z",
|
|
932
|
+
"modified_on": "2026-08-01T10:14:22Z"
|
|
933
|
+
}
|
|
934
|
+
}
|
|
935
|
+
}
|
|
936
|
+
```
|
|
937
|
+
|
|
938
|
+
`attempt_count`, `next_payment_attempt`, and `payment_link` are also included on `invoice.created` and `invoice.paid` payloads. `failure_details` (with `code`, `message`, and `payment_method_type`) describes the most recent failed attempt and is `null` once the invoice moves past that attempt (e.g. a later `invoice.paid` for the same invoice). `payment_link` is `null` whenever the invoice isn't currently payable (e.g. already paid).
|
|
939
|
+
|
|
729
940
|
```json
|
|
730
941
|
{
|
|
731
942
|
"id": "6e76547b-9b6b-4504-af36-c8f646fa91fe",
|
|
@@ -741,6 +952,21 @@ The request body is a JSON object with the following top-level fields:
|
|
|
741
952
|
"currency": "USD",
|
|
742
953
|
"reason": "REQUESTED_BY_CUSTOMER",
|
|
743
954
|
"order_id": "ORD-20260402042513-8M80C",
|
|
955
|
+
"customer": {
|
|
956
|
+
"id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
957
|
+
"name": "Geo Jacob",
|
|
958
|
+
"email": "geojacob@example.com",
|
|
959
|
+
"customer_id": "geo-jacob",
|
|
960
|
+
"billing_address": {
|
|
961
|
+
"line1": null,
|
|
962
|
+
"line2": null,
|
|
963
|
+
"city": null,
|
|
964
|
+
"state": null,
|
|
965
|
+
"postal_code": "680121",
|
|
966
|
+
"country": "IN"
|
|
967
|
+
}
|
|
968
|
+
},
|
|
969
|
+
"subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
|
|
744
970
|
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
745
971
|
"created_on": "2026-04-02T05:41:21Z",
|
|
746
972
|
"modified_on": "2026-04-02T05:41:21Z"
|
|
@@ -764,12 +990,147 @@ The request body is a JSON object with the following top-level fields:
|
|
|
764
990
|
"currency": "USD",
|
|
765
991
|
"reason": "REQUESTED_BY_CUSTOMER",
|
|
766
992
|
"order_id": "ORD-20260402042513-8M80C",
|
|
993
|
+
"customer": {
|
|
994
|
+
"id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
995
|
+
"name": "Geo Jacob",
|
|
996
|
+
"email": "geojacob@example.com",
|
|
997
|
+
"customer_id": "geo-jacob",
|
|
998
|
+
"billing_address": {
|
|
999
|
+
"line1": null,
|
|
1000
|
+
"line2": null,
|
|
1001
|
+
"city": null,
|
|
1002
|
+
"state": null,
|
|
1003
|
+
"postal_code": "680121",
|
|
1004
|
+
"country": "IN"
|
|
1005
|
+
}
|
|
1006
|
+
},
|
|
1007
|
+
"subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
|
|
767
1008
|
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
768
1009
|
"created_on": "2026-04-02T05:41:21Z",
|
|
769
1010
|
"modified_on": "2026-04-02T05:41:30Z"
|
|
770
|
-
}
|
|
771
|
-
|
|
772
|
-
|
|
1011
|
+
}
|
|
1012
|
+
}
|
|
1013
|
+
}
|
|
1014
|
+
```
|
|
1015
|
+
|
|
1016
|
+
```json
|
|
1017
|
+
{
|
|
1018
|
+
"id": "7f9c9a3e-2b41-4b7a-9d2e-5c8f1a6b3d4e",
|
|
1019
|
+
"type": "payment_method.created",
|
|
1020
|
+
"created_at": "2026-04-02T06:12:04Z",
|
|
1021
|
+
"data": {
|
|
1022
|
+
"object": {
|
|
1023
|
+
"id": 482,
|
|
1024
|
+
"object": "payment_method",
|
|
1025
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
1026
|
+
"customer_id": "geo-jacob",
|
|
1027
|
+
"customer": {
|
|
1028
|
+
"id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
|
|
1029
|
+
"name": "Geo Jacob",
|
|
1030
|
+
"email": "geojacob@example.com",
|
|
1031
|
+
"customer_id": "geo-jacob",
|
|
1032
|
+
"billing_address": {
|
|
1033
|
+
"line1": null,
|
|
1034
|
+
"line2": null,
|
|
1035
|
+
"city": null,
|
|
1036
|
+
"state": null,
|
|
1037
|
+
"postal_code": "680121",
|
|
1038
|
+
"country": "IN"
|
|
1039
|
+
}
|
|
1040
|
+
},
|
|
1041
|
+
"method_type": "card",
|
|
1042
|
+
"method_data": {
|
|
1043
|
+
"brand": "visa",
|
|
1044
|
+
"last4": "4242",
|
|
1045
|
+
"exp_month": 12,
|
|
1046
|
+
"exp_year": 2029,
|
|
1047
|
+
"funding": "credit",
|
|
1048
|
+
"country": "US"
|
|
1049
|
+
},
|
|
1050
|
+
"is_default": true,
|
|
1051
|
+
"status": "succeeded"
|
|
1052
|
+
}
|
|
1053
|
+
}
|
|
1054
|
+
}
|
|
1055
|
+
```
|
|
1056
|
+
|
|
1057
|
+
```json
|
|
1058
|
+
{
|
|
1059
|
+
"id": "b1d4e5f6-3c72-4a9b-8e1d-6f2a9c4b7e8d",
|
|
1060
|
+
"type": "payment_method.updated",
|
|
1061
|
+
"created_at": "2026-04-02T06:15:47Z",
|
|
1062
|
+
"data": {
|
|
1063
|
+
"object": {
|
|
1064
|
+
"id": 482,
|
|
1065
|
+
"object": "payment_method",
|
|
1066
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
1067
|
+
"customer_id": "geo-jacob",
|
|
1068
|
+
"customer": {
|
|
1069
|
+
"id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
|
|
1070
|
+
"name": "Geo Jacob",
|
|
1071
|
+
"email": "geojacob@example.com",
|
|
1072
|
+
"customer_id": "geo-jacob",
|
|
1073
|
+
"billing_address": {
|
|
1074
|
+
"line1": null,
|
|
1075
|
+
"line2": null,
|
|
1076
|
+
"city": null,
|
|
1077
|
+
"state": null,
|
|
1078
|
+
"postal_code": "680121",
|
|
1079
|
+
"country": "IN"
|
|
1080
|
+
}
|
|
1081
|
+
},
|
|
1082
|
+
"method_type": "card",
|
|
1083
|
+
"method_data": {
|
|
1084
|
+
"brand": "visa",
|
|
1085
|
+
"last4": "4242",
|
|
1086
|
+
"exp_month": 12,
|
|
1087
|
+
"exp_year": 2029,
|
|
1088
|
+
"funding": "credit",
|
|
1089
|
+
"country": "US"
|
|
1090
|
+
},
|
|
1091
|
+
"is_default": true,
|
|
1092
|
+
"status": "succeeded"
|
|
1093
|
+
}
|
|
1094
|
+
}
|
|
1095
|
+
}
|
|
1096
|
+
```
|
|
1097
|
+
|
|
1098
|
+
```json
|
|
1099
|
+
{
|
|
1100
|
+
"id": "e3a2b1c0-9d8e-47f6-b5a4-1c2d3e4f5a6b",
|
|
1101
|
+
"type": "payment_method.deleted",
|
|
1102
|
+
"created_at": "2026-04-02T06:20:12Z",
|
|
1103
|
+
"data": {
|
|
1104
|
+
"object": {
|
|
1105
|
+
"id": 482,
|
|
1106
|
+
"object": "payment_method",
|
|
1107
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
1108
|
+
"customer_id": "geo-jacob",
|
|
1109
|
+
"customer": {
|
|
1110
|
+
"id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
|
|
1111
|
+
"name": "Geo Jacob",
|
|
1112
|
+
"email": "geojacob@example.com",
|
|
1113
|
+
"customer_id": "geo-jacob",
|
|
1114
|
+
"billing_address": {
|
|
1115
|
+
"line1": null,
|
|
1116
|
+
"line2": null,
|
|
1117
|
+
"city": null,
|
|
1118
|
+
"state": null,
|
|
1119
|
+
"postal_code": "680121",
|
|
1120
|
+
"country": "IN"
|
|
1121
|
+
}
|
|
1122
|
+
},
|
|
1123
|
+
"method_type": "card",
|
|
1124
|
+
"method_data": {
|
|
1125
|
+
"brand": "visa",
|
|
1126
|
+
"last4": "4242",
|
|
1127
|
+
"exp_month": 12,
|
|
1128
|
+
"exp_year": 2029,
|
|
1129
|
+
"funding": "credit",
|
|
1130
|
+
"country": "US"
|
|
1131
|
+
},
|
|
1132
|
+
"is_default": false,
|
|
1133
|
+
"status": "succeeded"
|
|
773
1134
|
}
|
|
774
1135
|
}
|
|
775
1136
|
}
|
|
@@ -1031,7 +1392,7 @@ func main() {
|
|
|
1031
1392
|
## Best Practices
|
|
1032
1393
|
|
|
1033
1394
|
- **Return `2xx` fast.** Acknowledge the webhook immediately and process it asynchronously. Long-running handlers increase the risk of timeouts and duplicate retries.
|
|
1034
|
-
- **Make handlers idempotent.** The same event may be delivered more than once. Use `
|
|
1395
|
+
- **Make handlers idempotent.** The same event may be delivered more than once. Use the top-level event `id` or the `webhook-id` header as the deduplication key.
|
|
1035
1396
|
- **Validate the timestamp.** Reject requests where `webhook-timestamp` is more than 5 minutes from your server's clock to prevent replay attacks.
|
|
1036
1397
|
- **Use `hmac.compare_digest` / `hmac.Equal` / `crypto.timingSafeEqual`.** Constant-time comparison prevents timing side-channel attacks.
|
|
1037
1398
|
- **Store the raw body before parsing.** Signature verification operates on the raw bytes, not the deserialized object.
|
package/dist/docs/manifest.json
CHANGED
|
@@ -41,6 +41,13 @@
|
|
|
41
41
|
"description": "Changelog for the Kelviq Dashboard",
|
|
42
42
|
"path": "changelog/app.md"
|
|
43
43
|
},
|
|
44
|
+
{
|
|
45
|
+
"slug": "changelog/cli",
|
|
46
|
+
"section": "changelog",
|
|
47
|
+
"title": "CLI",
|
|
48
|
+
"description": "Changelog for @kelviq/cli",
|
|
49
|
+
"path": "changelog/cli.md"
|
|
50
|
+
},
|
|
44
51
|
{
|
|
45
52
|
"slug": "changelog/js-promotions-ui",
|
|
46
53
|
"section": "changelog",
|
|
@@ -83,6 +90,13 @@
|
|
|
83
90
|
"description": "Changelog for @kelviq/react-sdk",
|
|
84
91
|
"path": "changelog/react-sdk.md"
|
|
85
92
|
},
|
|
93
|
+
{
|
|
94
|
+
"slug": "checkout/apply-a-discount-code",
|
|
95
|
+
"section": "checkout",
|
|
96
|
+
"title": "Apply a discount code at checkout",
|
|
97
|
+
"description": "Let customers enter a discount code or pre-apply one to a Kelviq checkout",
|
|
98
|
+
"path": "checkout/apply-a-discount-code.md"
|
|
99
|
+
},
|
|
86
100
|
{
|
|
87
101
|
"slug": "checkout/checkout-configuration",
|
|
88
102
|
"section": "checkout",
|
|
@@ -90,6 +104,20 @@
|
|
|
90
104
|
"description": "Configure and customize checkout experiences for your customers",
|
|
91
105
|
"path": "checkout/checkout-configuration.md"
|
|
92
106
|
},
|
|
107
|
+
{
|
|
108
|
+
"slug": "checkout/checkout-metadata",
|
|
109
|
+
"section": "checkout",
|
|
110
|
+
"title": "Add metadata to checkout",
|
|
111
|
+
"description": "Attach your own IDs and context to a checkout session, then read them from the checkout.completed webhook",
|
|
112
|
+
"path": "checkout/checkout-metadata.md"
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
"slug": "checkout/static-checkout-url",
|
|
116
|
+
"section": "checkout",
|
|
117
|
+
"title": "Customize a static checkout URL",
|
|
118
|
+
"description": "Choose plans, set a billing period, attach a customer, apply a discount, and control the success redirect in a Kelviq checkout link",
|
|
119
|
+
"path": "checkout/static-checkout-url.md"
|
|
120
|
+
},
|
|
93
121
|
{
|
|
94
122
|
"slug": "cli/commands",
|
|
95
123
|
"section": "cli",
|
|
@@ -128,8 +156,8 @@
|
|
|
128
156
|
{
|
|
129
157
|
"slug": "customer-portal/managing-payment-methods",
|
|
130
158
|
"section": "customer-portal",
|
|
131
|
-
"title": "Managing
|
|
132
|
-
"description": "
|
|
159
|
+
"title": "Managing payment methods",
|
|
160
|
+
"description": "How your customers add, update, and remove payment methods",
|
|
133
161
|
"path": "customer-portal/managing-payment-methods.md"
|
|
134
162
|
},
|
|
135
163
|
{
|
|
@@ -178,7 +206,7 @@
|
|
|
178
206
|
"slug": "getstarted/fees",
|
|
179
207
|
"section": "getstarted",
|
|
180
208
|
"title": "Fees",
|
|
181
|
-
"description": "Kelviq's
|
|
209
|
+
"description": "Understand Kelviq's transaction fees and additional charges",
|
|
182
210
|
"path": "getstarted/fees.md"
|
|
183
211
|
},
|
|
184
212
|
{
|
|
@@ -195,6 +223,13 @@
|
|
|
195
223
|
"description": null,
|
|
196
224
|
"path": "getstarted/merchant-of-record.md"
|
|
197
225
|
},
|
|
226
|
+
{
|
|
227
|
+
"slug": "getstarted/payment-security-and-seller-funds",
|
|
228
|
+
"section": "getstarted",
|
|
229
|
+
"title": "Payment security and seller funds",
|
|
230
|
+
"description": "How Kelviq protects card details, routes payments through Stripe, and handles payouts, account reviews, and migrations",
|
|
231
|
+
"path": "getstarted/payment-security-and-seller-funds.md"
|
|
232
|
+
},
|
|
198
233
|
{
|
|
199
234
|
"slug": "getstarted/review-process",
|
|
200
235
|
"section": "getstarted",
|
|
@@ -202,6 +237,13 @@
|
|
|
202
237
|
"description": null,
|
|
203
238
|
"path": "getstarted/review-process.md"
|
|
204
239
|
},
|
|
240
|
+
{
|
|
241
|
+
"slug": "guides/agent-toolkit",
|
|
242
|
+
"section": "guides",
|
|
243
|
+
"title": "Agent Toolkit",
|
|
244
|
+
"description": "Install Kelviq into Claude Code with one plugin — or add the Kelviq skills to any of 70+ AI coding agents.",
|
|
245
|
+
"path": "guides/agent-toolkit.md"
|
|
246
|
+
},
|
|
205
247
|
{
|
|
206
248
|
"slug": "guides/mcp-server",
|
|
207
249
|
"section": "guides",
|
|
@@ -209,6 +251,13 @@
|
|
|
209
251
|
"description": "Control Kelviq from Claude, Cursor, and any AI assistant that speaks the Model Context Protocol.",
|
|
210
252
|
"path": "guides/mcp-server.md"
|
|
211
253
|
},
|
|
254
|
+
{
|
|
255
|
+
"slug": "guides/migrate-from-cashfree",
|
|
256
|
+
"section": "guides",
|
|
257
|
+
"title": "Migrate from Cashfree",
|
|
258
|
+
"description": "Get help moving from Cashfree to Kelviq",
|
|
259
|
+
"path": "guides/migrate-from-cashfree.md"
|
|
260
|
+
},
|
|
212
261
|
{
|
|
213
262
|
"slug": "guides/sandbox",
|
|
214
263
|
"section": "guides",
|
|
@@ -321,6 +370,20 @@
|
|
|
321
370
|
"description": "Audit individual payments, fees, and net earnings",
|
|
322
371
|
"path": "payouts/transactions.md"
|
|
323
372
|
},
|
|
373
|
+
{
|
|
374
|
+
"slug": "product-catalog/create-a-feature",
|
|
375
|
+
"section": "product-catalog",
|
|
376
|
+
"title": "Create a feature in Kelviq",
|
|
377
|
+
"description": "Create Boolean, Meter, or Customizable features in the Kelviq dashboard or with the API, then add them to a plan as entitlements.",
|
|
378
|
+
"path": "product-catalog/create-a-feature.md"
|
|
379
|
+
},
|
|
380
|
+
{
|
|
381
|
+
"slug": "product-catalog/create-an-enterprise-plan",
|
|
382
|
+
"section": "product-catalog",
|
|
383
|
+
"title": "Create an Enterprise plan",
|
|
384
|
+
"description": "Set up a reusable Enterprise tier or a bespoke customer deal in Kelviq",
|
|
385
|
+
"path": "product-catalog/create-an-enterprise-plan.md"
|
|
386
|
+
},
|
|
324
387
|
{
|
|
325
388
|
"slug": "product-catalog/digital-downloads",
|
|
326
389
|
"section": "product-catalog",
|
|
@@ -377,6 +440,13 @@
|
|
|
377
440
|
"description": "Charge a flat fee for lifetime access or digital downloads",
|
|
378
441
|
"path": "product-catalog/one-time-payments.md"
|
|
379
442
|
},
|
|
443
|
+
{
|
|
444
|
+
"slug": "product-catalog/pay-as-you-go",
|
|
445
|
+
"section": "product-catalog",
|
|
446
|
+
"title": "Pay as you go",
|
|
447
|
+
"description": "Bill customers each month for the usage they record",
|
|
448
|
+
"path": "product-catalog/pay-as-you-go.md"
|
|
449
|
+
},
|
|
380
450
|
{
|
|
381
451
|
"slug": "product-catalog/plans",
|
|
382
452
|
"section": "product-catalog",
|
|
@@ -391,11 +461,18 @@
|
|
|
391
461
|
"description": "Create and manage your high-level product containers",
|
|
392
462
|
"path": "product-catalog/products.md"
|
|
393
463
|
},
|
|
464
|
+
{
|
|
465
|
+
"slug": "product-catalog/seat-based-pricing",
|
|
466
|
+
"section": "product-catalog",
|
|
467
|
+
"title": "Seat based pricing",
|
|
468
|
+
"description": "Charge teams for the number of seats they purchase",
|
|
469
|
+
"path": "product-catalog/seat-based-pricing.md"
|
|
470
|
+
},
|
|
394
471
|
{
|
|
395
472
|
"slug": "product-catalog/subscriptions",
|
|
396
473
|
"section": "product-catalog",
|
|
397
474
|
"title": "Subscriptions",
|
|
398
|
-
"description": "Set up
|
|
475
|
+
"description": "Set up recurring billing and understand renewals and failed payments",
|
|
399
476
|
"path": "product-catalog/subscriptions.md"
|
|
400
477
|
},
|
|
401
478
|
{
|
|
@@ -405,6 +482,13 @@
|
|
|
405
482
|
"description": "Configure price display rules and B2B exemptions",
|
|
406
483
|
"path": "product-catalog/tax-settings.md"
|
|
407
484
|
},
|
|
485
|
+
{
|
|
486
|
+
"slug": "product-catalog/usage-alerts",
|
|
487
|
+
"section": "product-catalog",
|
|
488
|
+
"title": "Usage alerts",
|
|
489
|
+
"description": "Configure usage thresholds and receive feature.usage_alert webhooks",
|
|
490
|
+
"path": "product-catalog/usage-alerts.md"
|
|
491
|
+
},
|
|
408
492
|
{
|
|
409
493
|
"slug": "product-catalog/usage-based-billing",
|
|
410
494
|
"section": "product-catalog",
|
|
@@ -461,6 +545,13 @@
|
|
|
461
545
|
"description": null,
|
|
462
546
|
"path": "quickstart/integrate-with-your-app.md"
|
|
463
547
|
},
|
|
548
|
+
{
|
|
549
|
+
"slug": "sales/abandoned-cart-recovery",
|
|
550
|
+
"section": "sales",
|
|
551
|
+
"title": "Abandoned cart recovery",
|
|
552
|
+
"description": "Automatically remind customers who start checkout but do not pay",
|
|
553
|
+
"path": "sales/abandoned-cart-recovery.md"
|
|
554
|
+
},
|
|
464
555
|
{
|
|
465
556
|
"slug": "sales/checkout-sessions",
|
|
466
557
|
"section": "sales",
|
|
@@ -468,6 +559,13 @@
|
|
|
468
559
|
"description": "Monitor live traffic and debug failed purchase attempts",
|
|
469
560
|
"path": "sales/checkout-sessions.md"
|
|
470
561
|
},
|
|
562
|
+
{
|
|
563
|
+
"slug": "sales/create-a-one-time-charge",
|
|
564
|
+
"section": "sales",
|
|
565
|
+
"title": "Create a one-time charge",
|
|
566
|
+
"description": "Charge a customer's saved payment method without sending them through checkout",
|
|
567
|
+
"path": "sales/create-a-one-time-charge.md"
|
|
568
|
+
},
|
|
471
569
|
{
|
|
472
570
|
"slug": "sales/orders",
|
|
473
571
|
"section": "sales",
|