@kelviq/mcp-server 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +22 -20
  2. package/dist/config.d.ts +8 -2
  3. package/dist/config.js +42 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/api-reference/authentication.md +7 -3
  6. package/dist/docs/api-reference/introduction.md +143 -0
  7. package/dist/docs/backend-integration/node-sdk.md +148 -6
  8. package/dist/docs/backend-integration/python-sdk.md +195 -11
  9. package/dist/docs/changelog/api.md +119 -0
  10. package/dist/docs/changelog/app.md +693 -0
  11. package/dist/docs/changelog/node-sdk.md +153 -0
  12. package/dist/docs/changelog/python-sdk.md +182 -0
  13. package/dist/docs/cli/commands.md +225 -0
  14. package/dist/docs/cli/environments.md +95 -0
  15. package/dist/docs/cli/kelviq-config.md +141 -0
  16. package/dist/docs/cli/overview.md +223 -0
  17. package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
  18. package/dist/docs/guides/mcp-server.md +374 -0
  19. package/dist/docs/guides/sandbox.md +107 -0
  20. package/dist/docs/guides/webhooks.md +81 -0
  21. package/dist/docs/manifest.json +64 -8
  22. package/dist/docs/openapi.json +1208 -52
  23. package/dist/docs/product-catalog/one-time-payments.md +3 -1
  24. package/dist/docs/product-catalog/usage-based-billing.md +86 -7
  25. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  26. package/dist/http/client.d.ts +1 -1
  27. package/dist/http/client.js +1 -5
  28. package/dist/http/client.js.map +1 -1
  29. package/dist/schemas/kelviq.d.ts +0 -128
  30. package/dist/schemas/kelviq.js +0 -63
  31. package/dist/schemas/kelviq.js.map +1 -1
  32. package/dist/server.js +2 -2
  33. package/dist/server.js.map +1 -1
  34. package/dist/tools/entitlements.js +1 -1
  35. package/dist/tools/entitlements.js.map +1 -1
  36. package/dist/tools/index.js +0 -4
  37. package/dist/tools/index.js.map +1 -1
  38. package/dist/tools/plan-files.js +1 -1
  39. package/dist/tools/plan-files.js.map +1 -1
  40. package/dist/tools/plans.js +1 -15
  41. package/dist/tools/plans.js.map +1 -1
  42. package/dist/tools/portal.d.ts +11 -1
  43. package/dist/tools/portal.js +27 -2
  44. package/dist/tools/portal.js.map +1 -1
  45. package/dist/tools/products.js +1 -1
  46. package/dist/tools/products.js.map +1 -1
  47. package/dist/tools/subscriptions.js +1 -1
  48. package/dist/tools/subscriptions.js.map +1 -1
  49. package/package.json +5 -2
@@ -6,9 +6,13 @@
6
6
  "description": "API for interacting with kelviq services, derived from Python SDK documentation."
7
7
  },
8
8
  "servers": [
9
+ {
10
+ "url": "https://sandboxapi.kelviq.com/api/v1",
11
+ "description": "Sandbox — Test payments"
12
+ },
9
13
  {
10
14
  "url": "https://api.kelviq.com/api/v1",
11
- "description": "kelviq API Server (General - specific operations might override)"
15
+ "description": "Production — Live payments"
12
16
  }
13
17
  ],
14
18
  "tags": [
@@ -20,7 +24,9 @@
20
24
  { "name": "Plan Entitlements", "description": "Feature entitlements attached to a plan." },
21
25
  { "name": "Plan Files", "description": "Files attached to plans, and signed download links." },
22
26
  { "name": "Media", "description": "Generate presigned S3 upload URLs for product/plan images and files." },
23
- { "name": "Partner", "description": "Partner integration APIs (organization provisioning, lookup)." }
27
+ { "name": "Partner", "description": "Partner integration APIs (organization provisioning, lookup)." },
28
+ { "name": "Charges", "description": "One-time payments charged immediately against a customer's default payment method." },
29
+ { "name": "Refunds", "description": "Full and partial refunds for paid orders." }
24
30
  ],
25
31
  "components": {
26
32
  "securitySchemes": {
@@ -154,6 +160,30 @@
154
160
  }
155
161
  }
156
162
  },
163
+ "CustomerListResponse": {
164
+ "type": "object",
165
+ "properties": {
166
+ "count": {
167
+ "type": "integer"
168
+ },
169
+ "next": {
170
+ "type": "string",
171
+ "format": "uri",
172
+ "nullable": true
173
+ },
174
+ "previous": {
175
+ "type": "string",
176
+ "format": "uri",
177
+ "nullable": true
178
+ },
179
+ "results": {
180
+ "type": "array",
181
+ "items": {
182
+ "$ref": "#/components/schemas/CustomerResponse"
183
+ }
184
+ }
185
+ }
186
+ },
157
187
  "CustomerCreateRequest": {
158
188
  "type": "object",
159
189
  "required": [
@@ -277,6 +307,7 @@
277
307
  "YEARLY",
278
308
  "WEEKLY",
279
309
  "DAILY",
310
+ "TWENTY_EIGHT_DAYS",
280
311
  "THREE_MONTHS",
281
312
  "SIX_MONTHS"
282
313
  ],
@@ -346,6 +377,12 @@
346
377
  "description": "Whether discount/coupon code entry is shown on the checkout page. Defaults to `true`.",
347
378
  "example": false
348
379
  },
380
+ "discountCode": {
381
+ "type": "string",
382
+ "nullable": true,
383
+ "description": "A discount/coupon code to pre-apply to the checkout session. The code is applied only if it is active, unexpired, and valid for the selected plan; otherwise the request fails with an error.",
384
+ "example": "WELCOME20"
385
+ },
349
386
  "lockEmail": {
350
387
  "type": "boolean",
351
388
  "nullable": true,
@@ -357,6 +394,16 @@
357
394
  "nullable": true,
358
395
  "description": "ISO 3166-1 alpha-2 country code used to pre-fill the billing address country on the checkout page.",
359
396
  "example": "US"
397
+ },
398
+ "metadata": {
399
+ "type": "object",
400
+ "additionalProperties": true,
401
+ "nullable": true,
402
+ "description": "Arbitrary key-value pairs to attach to the checkout session. The keys are preserved verbatim and the object is returned unchanged on the `checkout.completed` webhook payload's `metadata` field.",
403
+ "example": {
404
+ "order_ref": "ABC-123",
405
+ "source": "pricing_page"
406
+ }
360
407
  }
361
408
  }
362
409
  },
@@ -832,6 +879,7 @@
832
879
  "YEARLY",
833
880
  "WEEKLY",
834
881
  "DAILY",
882
+ "TWENTY_EIGHT_DAYS",
835
883
  "THREE_MONTHS",
836
884
  "SIX_MONTHS"
837
885
  ],
@@ -969,6 +1017,195 @@
969
1017
  "type": "string",
970
1018
  "description": "The customer identifier associated with this subscription.",
971
1019
  "example": "geojacob"
1020
+ },
1021
+ "files": {
1022
+ "type": "array",
1023
+ "description": "Downloadable files attached to the subscription's plan.",
1024
+ "items": {
1025
+ "$ref": "#/components/schemas/PlanFile"
1026
+ }
1027
+ },
1028
+ "links": {
1029
+ "type": "array",
1030
+ "description": "External links attached to the subscription's plan.",
1031
+ "items": {
1032
+ "$ref": "#/components/schemas/PlanLink"
1033
+ }
1034
+ },
1035
+ "license": {
1036
+ "type": "array",
1037
+ "description": "Issued licenses associated with the subscription.",
1038
+ "items": {
1039
+ "$ref": "#/components/schemas/SubscriptionLicense"
1040
+ }
1041
+ }
1042
+ }
1043
+ },
1044
+ "CreateChargeRequest": {
1045
+ "type": "object",
1046
+ "required": [
1047
+ "planIdentifier",
1048
+ "chargePeriod",
1049
+ "customerId"
1050
+ ],
1051
+ "properties": {
1052
+ "planIdentifier": {
1053
+ "type": "string",
1054
+ "description": "The identifier of the plan being purchased as a one-time payment.",
1055
+ "example": "lifetime-access"
1056
+ },
1057
+ "chargePeriod": {
1058
+ "type": "string",
1059
+ "description": "Must be `ONE_TIME`. Any other value is rejected.",
1060
+ "enum": [
1061
+ "ONE_TIME"
1062
+ ],
1063
+ "example": "ONE_TIME"
1064
+ },
1065
+ "customerId": {
1066
+ "type": "string",
1067
+ "description": "The ID of the customer being charged. The customer must already have a default payment method on file.",
1068
+ "example": "cust_789"
1069
+ },
1070
+ "features": {
1071
+ "type": "array",
1072
+ "items": {
1073
+ "$ref": "#/components/schemas/FeatureInput"
1074
+ },
1075
+ "nullable": true,
1076
+ "description": "A list of features and their desired quantities.",
1077
+ "example": [
1078
+ {
1079
+ "identifier": "seats",
1080
+ "quantity": 5
1081
+ }
1082
+ ]
1083
+ },
1084
+ "currencyCode": {
1085
+ "type": "string",
1086
+ "nullable": true,
1087
+ "description": "Optional ISO 4217 currency code to charge in. Must match the customer's currency if they already have one set.",
1088
+ "example": "USD"
1089
+ },
1090
+ "ipAddress": {
1091
+ "type": "string",
1092
+ "nullable": true,
1093
+ "description": "The IP Address of the customer, used for location-based pricing.",
1094
+ "example": "103.154.35.20"
1095
+ }
1096
+ }
1097
+ },
1098
+ "CreateChargeResponse": {
1099
+ "type": "object",
1100
+ "properties": {
1101
+ "id": {
1102
+ "type": "string",
1103
+ "format": "uuid",
1104
+ "description": "The unique identifier of the created charge record.",
1105
+ "example": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11"
1106
+ },
1107
+ "startDate": {
1108
+ "type": "string",
1109
+ "format": "date",
1110
+ "description": "The date the one-time payment was created.",
1111
+ "example": "2026-06-20"
1112
+ },
1113
+ "endDate": {
1114
+ "type": "string",
1115
+ "format": "date",
1116
+ "nullable": true,
1117
+ "description": "Always null for one-time payments.",
1118
+ "example": null
1119
+ },
1120
+ "billingPeriodStartTime": {
1121
+ "type": "string",
1122
+ "format": "date-time",
1123
+ "nullable": true,
1124
+ "description": "Not applicable for one-time payments.",
1125
+ "example": null
1126
+ },
1127
+ "billingPeriodEndTime": {
1128
+ "type": "string",
1129
+ "format": "date-time",
1130
+ "nullable": true,
1131
+ "description": "Not applicable for one-time payments.",
1132
+ "example": null
1133
+ },
1134
+ "amount": {
1135
+ "type": "string",
1136
+ "description": "The amount charged.",
1137
+ "example": "49.00"
1138
+ },
1139
+ "recurrence": {
1140
+ "type": "string",
1141
+ "description": "Empty for one-time payments.",
1142
+ "example": ""
1143
+ },
1144
+ "currency": {
1145
+ "type": "string",
1146
+ "description": "The currency of the payment.",
1147
+ "example": "USD"
1148
+ },
1149
+ "status": {
1150
+ "type": "string",
1151
+ "description": "The status of the resulting record.",
1152
+ "example": "active"
1153
+ },
1154
+ "product": {
1155
+ "type": "object",
1156
+ "properties": {
1157
+ "name": {
1158
+ "type": "string",
1159
+ "description": "The name of the product.",
1160
+ "example": "Invoice Test"
1161
+ },
1162
+ "id": {
1163
+ "type": "string",
1164
+ "format": "uuid",
1165
+ "description": "The unique identifier of the product.",
1166
+ "example": "88e437b8-6017-405b-9328-e0f4e140bb79"
1167
+ },
1168
+ "identifier": {
1169
+ "type": "string",
1170
+ "description": "The identifier of the product.",
1171
+ "example": "invoice-test"
1172
+ }
1173
+ }
1174
+ },
1175
+ "plan": {
1176
+ "type": "object",
1177
+ "properties": {
1178
+ "name": {
1179
+ "type": "string",
1180
+ "description": "The name of the plan.",
1181
+ "example": "Lifetime Access"
1182
+ },
1183
+ "identifier": {
1184
+ "type": "string",
1185
+ "description": "The identifier of the plan.",
1186
+ "example": "lifetime-access"
1187
+ }
1188
+ }
1189
+ },
1190
+ "features": {
1191
+ "type": "array",
1192
+ "items": {},
1193
+ "description": "List of features included in the purchase."
1194
+ },
1195
+ "trialDaysRemaining": {
1196
+ "type": "integer",
1197
+ "description": "Always 0 for one-time payments.",
1198
+ "example": 0
1199
+ },
1200
+ "customerId": {
1201
+ "type": "string",
1202
+ "description": "The customer identifier associated with this payment.",
1203
+ "example": "geojacob"
1204
+ },
1205
+ "billingType": {
1206
+ "type": "string",
1207
+ "description": "The billing type of the record.",
1208
+ "example": "ONE_TIME"
972
1209
  }
973
1210
  }
974
1211
  },
@@ -1156,6 +1393,7 @@
1156
1393
  "YEARLY",
1157
1394
  "WEEKLY",
1158
1395
  "DAILY",
1396
+ "TWENTY_EIGHT_DAYS",
1159
1397
  "THREE_MONTHS",
1160
1398
  "SIX_MONTHS"
1161
1399
  ],
@@ -1185,8 +1423,17 @@
1185
1423
  "trialEnd": {
1186
1424
  "type": "string",
1187
1425
  "nullable": true,
1188
- "description": "Controls the trial period for the updated subscription. Accepts either the literal string `\"now\"` to end any active trial immediately, or an ISO 8601 datetime string (e.g. `\"2025-05-22 08:27:45.430732\"`) to set a new trial end date. The datetime must be in the future. If omitted, the existing trial behavior is preserved.",
1189
- "example": "2025-12-31 23:59:59"
1426
+ "description": "Controls the trial period for the updated subscription. Accepts either the literal string `\"now\"` to end any active trial immediately, or 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. If omitted, the existing trial behavior is preserved.",
1427
+ "example": "2027-12-31 23:59:59"
1428
+ },
1429
+ "paymentBehavior": {
1430
+ "type": "string",
1431
+ "enum": [
1432
+ "activate_on_payment"
1433
+ ],
1434
+ "nullable": true,
1435
+ "description": "Controls when a paid subscription update takes effect. Set to `\"activate_on_payment\"` to keep the current subscription active while payment is pending and apply the new plan, charge period, and features only after payment succeeds. If payment is not completed, the pending update expires and the current subscription remains unchanged. If omitted, the update uses the default immediate behavior.",
1436
+ "example": "activate_on_payment"
1190
1437
  }
1191
1438
  }
1192
1439
  },
@@ -1754,6 +2001,27 @@
1754
2001
  "recurrenceType": {
1755
2002
  "type": "string",
1756
2003
  "nullable": true
2004
+ },
2005
+ "files": {
2006
+ "type": "array",
2007
+ "description": "Downloadable files attached to the subscription's plan.",
2008
+ "items": {
2009
+ "$ref": "#/components/schemas/PlanFile"
2010
+ }
2011
+ },
2012
+ "links": {
2013
+ "type": "array",
2014
+ "description": "External links attached to the subscription's plan.",
2015
+ "items": {
2016
+ "$ref": "#/components/schemas/PlanLink"
2017
+ }
2018
+ },
2019
+ "license": {
2020
+ "type": "array",
2021
+ "description": "Issued licenses associated with the subscription.",
2022
+ "items": {
2023
+ "$ref": "#/components/schemas/SubscriptionLicense"
2024
+ }
1757
2025
  }
1758
2026
  }
1759
2027
  },
@@ -2400,9 +2668,9 @@
2400
2668
  "PlanFile": {
2401
2669
  "type": "object",
2402
2670
  "properties": {
2403
- "id": { "type": "string", "format": "uuid", "readOnly": true, "example": "7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0" },
2404
- "name": { "type": "string", "example": "Plan Terms.pdf" },
2405
- "file": { "type": "string", "readOnly": true, "example": "media/.../plans/<id>/<uuid>/terms.pdf" },
2671
+ "id": { "type": "string", "format": "uuid", "readOnly": true, "example": "bf9f0fe0-c9c0-436d-8811-e412d0365470" },
2672
+ "name": { "type": "string", "example": "custom-pricinig.png" },
2673
+ "file": { "type": "string", "format": "uri", "readOnly": true, "example": "https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png" },
2406
2674
  "ordering": { "type": "integer", "example": 0 },
2407
2675
  "enabled": { "type": "boolean", "example": true },
2408
2676
  "downloadUrl": {
@@ -2410,7 +2678,57 @@
2410
2678
  "format": "uri",
2411
2679
  "readOnly": true,
2412
2680
  "description": "URL clients can hit to download the file. Will redirect to a forced-download URL.",
2413
- "example": "https://api.kelviq.com/api/v1/catalog/plans/pro-monthly/file/7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0/download/"
2681
+ "example": "https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/"
2682
+ }
2683
+ }
2684
+ },
2685
+ "SubscriptionLicense": {
2686
+ "type": "object",
2687
+ "description": "An issued license associated with a subscription.",
2688
+ "properties": {
2689
+ "id": {
2690
+ "type": "string",
2691
+ "format": "uuid",
2692
+ "nullable": true,
2693
+ "example": "f81efb90-5f29-4dd1-9c7b-be4085e473de"
2694
+ },
2695
+ "licenseKey": {
2696
+ "type": "string",
2697
+ "nullable": true,
2698
+ "description": "The issued license key.",
2699
+ "example": "10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1"
2700
+ },
2701
+ "activatedOn": {
2702
+ "type": "string",
2703
+ "format": "date-time",
2704
+ "nullable": true,
2705
+ "description": "When the license was first activated.",
2706
+ "example": null
2707
+ },
2708
+ "expiresOn": {
2709
+ "type": "string",
2710
+ "format": "date-time",
2711
+ "nullable": true,
2712
+ "description": "When the license expires, if applicable.",
2713
+ "example": null
2714
+ },
2715
+ "activationUsage": {
2716
+ "type": "integer",
2717
+ "nullable": true,
2718
+ "description": "Number of currently active instances.",
2719
+ "example": 0
2720
+ },
2721
+ "activationLimit": {
2722
+ "type": "integer",
2723
+ "nullable": true,
2724
+ "description": "Maximum number of allowed concurrent activations.",
2725
+ "example": 2
2726
+ },
2727
+ "enabled": {
2728
+ "type": "boolean",
2729
+ "nullable": true,
2730
+ "description": "Whether the license is enabled.",
2731
+ "example": true
2414
2732
  }
2415
2733
  }
2416
2734
  },
@@ -2642,7 +2960,7 @@
2642
2960
  },
2643
2961
  "reset": {
2644
2962
  "type": "string",
2645
- "enum": ["NEVER", "EVERY_DAY", "EVERY_MONTH", "EVERY_QUARTER", "EVERY_YEAR"],
2963
+ "enum": ["NEVER", "EVERY_DAY", "EVERY_28_DAYS", "EVERY_MONTH", "EVERY_QUARTER", "EVERY_YEAR"],
2646
2964
  "example": "EVERY_MONTH"
2647
2965
  },
2648
2966
  "resetTime": {
@@ -2771,7 +3089,7 @@
2771
3089
  "hasUnlimitedUsage": { "type": "boolean", "example": false },
2772
3090
  "reset": {
2773
3091
  "type": "string",
2774
- "enum": ["NEVER", "EVERY_DAY", "EVERY_MONTH", "EVERY_QUARTER", "EVERY_YEAR"],
3092
+ "enum": ["NEVER", "EVERY_DAY", "EVERY_28_DAYS", "EVERY_MONTH", "EVERY_QUARTER", "EVERY_YEAR"],
2775
3093
  "example": "EVERY_MONTH"
2776
3094
  },
2777
3095
  "resetTime": { "type": "string", "nullable": true, "example": "BEGINNING_OF_PERIOD" },
@@ -3058,17 +3376,153 @@
3058
3376
  }
3059
3377
  }
3060
3378
  },
3061
- "PartnerOrganizationList": {
3379
+ "RefundCreateRequest": {
3062
3380
  "type": "object",
3063
- "description": "List response for partner organizations.",
3381
+ "description": "Parameters for a full or partial refund. Omit both amount fields to refund the order's entire remaining refundable balance.",
3064
3382
  "properties": {
3065
- "results": {
3066
- "type": "array",
3067
- "items": { "$ref": "#/components/schemas/PartnerOrganization" }
3383
+ "orderId": {
3384
+ "type": "string",
3385
+ "description": "The ID of an order owned by the authenticated organization.",
3386
+ "example": "ORD-20260715123000-A1B2C"
3068
3387
  },
3069
- "count": {
3388
+ "amountUnits": {
3070
3389
  "type": "integer",
3071
- "description": "Total number of organizations matching the query.",
3390
+ "format": "int64",
3391
+ "minimum": 1,
3392
+ "description": "Amount to refund in the currency's minor unit (for example, cents for USD). Takes precedence when `amount` is also provided.",
3393
+ "example": 2500
3394
+ },
3395
+ "amount": {
3396
+ "type": "number",
3397
+ "format": "decimal",
3398
+ "exclusiveMinimum": true,
3399
+ "minimum": 0,
3400
+ "description": "Amount to refund in the currency's major unit (for example, dollars for USD). Used only when `amountUnits` is omitted. For zero-decimal currencies, provide a whole number.",
3401
+ "example": 25
3402
+ },
3403
+ "reason": {
3404
+ "type": "string",
3405
+ "description": "Reason for the refund. Defaults to `REQUESTED_BY_CUSTOMER`.",
3406
+ "enum": [
3407
+ "DUPLICATE",
3408
+ "FRAUDULENT",
3409
+ "REQUESTED_BY_CUSTOMER",
3410
+ "OTHER"
3411
+ ],
3412
+ "example": "REQUESTED_BY_CUSTOMER"
3413
+ },
3414
+ "internalNote": {
3415
+ "type": "string",
3416
+ "nullable": true,
3417
+ "description": "Optional internal note associated with the refund.",
3418
+ "example": "Customer requested a partial refund."
3419
+ }
3420
+ },
3421
+ "required": ["orderId"]
3422
+ },
3423
+ "RefundListResponse": {
3424
+ "type": "object",
3425
+ "properties": {
3426
+ "count": {
3427
+ "type": "integer",
3428
+ "example": 1
3429
+ },
3430
+ "next": {
3431
+ "type": "string",
3432
+ "format": "uri",
3433
+ "nullable": true,
3434
+ "example": null
3435
+ },
3436
+ "previous": {
3437
+ "type": "string",
3438
+ "format": "uri",
3439
+ "nullable": true,
3440
+ "example": null
3441
+ },
3442
+ "results": {
3443
+ "type": "array",
3444
+ "items": {
3445
+ "$ref": "#/components/schemas/RefundResponse"
3446
+ }
3447
+ }
3448
+ }
3449
+ },
3450
+ "RefundResponse": {
3451
+ "type": "object",
3452
+ "description": "A refund returned by list, create, and retrieve operations.",
3453
+ "properties": {
3454
+ "id": {
3455
+ "type": "string",
3456
+ "format": "uuid",
3457
+ "example": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11"
3458
+ },
3459
+ "reason": {
3460
+ "type": "string",
3461
+ "nullable": true,
3462
+ "enum": [
3463
+ "DUPLICATE",
3464
+ "DASHBOARD_INITIATED",
3465
+ "FRAUDULENT",
3466
+ "REQUESTED_BY_CUSTOMER",
3467
+ "OTHER"
3468
+ ],
3469
+ "example": "REQUESTED_BY_CUSTOMER"
3470
+ },
3471
+ "amountUnits": {
3472
+ "type": "integer",
3473
+ "format": "int64",
3474
+ "example": 2500
3475
+ },
3476
+ "amount": {
3477
+ "type": "number",
3478
+ "format": "decimal",
3479
+ "example": 25
3480
+ },
3481
+ "internalNote": {
3482
+ "type": "string",
3483
+ "nullable": true,
3484
+ "example": "Customer requested a partial refund."
3485
+ },
3486
+ "failureReason": {
3487
+ "type": "string",
3488
+ "nullable": true,
3489
+ "example": null
3490
+ },
3491
+ "status": {
3492
+ "type": "string",
3493
+ "enum": ["PENDING", "PROCESSING", "SUCCEEDED", "FAILED", "CANCELED"],
3494
+ "example": "SUCCEEDED"
3495
+ },
3496
+ "order": {
3497
+ "type": "object",
3498
+ "description": "The complete serialized order associated with the refund.",
3499
+ "additionalProperties": true
3500
+ }
3501
+ }
3502
+ },
3503
+ "RefundErrorResponse": {
3504
+ "type": "object",
3505
+ "description": "Validation errors are keyed by request field. Payment-provider and business-logic errors use the `error` property.",
3506
+ "additionalProperties": true,
3507
+ "properties": {
3508
+ "error": {
3509
+ "type": "string",
3510
+ "description": "A human-readable validation, business logic, or payment-provider error.",
3511
+ "example": "Amount exceeds order total."
3512
+ }
3513
+ }
3514
+ },
3515
+ "PartnerOrganizationList": {
3516
+ "type": "object",
3517
+ "description": "List response for partner organizations.",
3518
+ "properties": {
3519
+ "results": {
3520
+ "type": "array",
3521
+ "items": { "$ref": "#/components/schemas/PartnerOrganization" }
3522
+ },
3523
+ "count": {
3524
+ "type": "integer",
3525
+ "description": "Total number of organizations matching the query.",
3072
3526
  "example": 1
3073
3527
  }
3074
3528
  }
@@ -3082,6 +3536,88 @@
3082
3536
  ],
3083
3537
  "paths": {
3084
3538
  "/customers/": {
3539
+ "get": {
3540
+ "tags": [
3541
+ "Customers"
3542
+ ],
3543
+ "summary": "List customers",
3544
+ "description": "Retrieves a paginated list of customers for your organization, ordered by creation date (newest first). You can search across the customer's name, email and `customerId`.",
3545
+ "operationId": "listCustomers",
3546
+ "x-mint": {
3547
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
3548
+ },
3549
+ "parameters": [
3550
+ {
3551
+ "name": "search",
3552
+ "in": "query",
3553
+ "required": false,
3554
+ "description": "Free-text search across the customer's `name`, `email` and `customerId`.",
3555
+ "schema": {
3556
+ "type": "string"
3557
+ }
3558
+ },
3559
+ {
3560
+ "name": "page_size",
3561
+ "in": "query",
3562
+ "required": false,
3563
+ "description": "Number of results to return per page. Defaults to 10, maximum 100.",
3564
+ "schema": {
3565
+ "type": "integer",
3566
+ "minimum": 1,
3567
+ "maximum": 100
3568
+ }
3569
+ },
3570
+ {
3571
+ "name": "page",
3572
+ "in": "query",
3573
+ "required": false,
3574
+ "description": "The page number of results to return.",
3575
+ "schema": {
3576
+ "type": "integer"
3577
+ }
3578
+ }
3579
+ ],
3580
+ "responses": {
3581
+ "200": {
3582
+ "description": "A paginated list of customers.",
3583
+ "content": {
3584
+ "application/json": {
3585
+ "schema": {
3586
+ "$ref": "#/components/schemas/CustomerListResponse"
3587
+ },
3588
+ "example": {
3589
+ "count": 1,
3590
+ "next": null,
3591
+ "previous": null,
3592
+ "results": [
3593
+ {
3594
+ "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
3595
+ "customerId": "unique-customer-id-123",
3596
+ "name": "John Doe",
3597
+ "email": "new.customer@example.com",
3598
+ "details": {},
3599
+ "metadata": {
3600
+ "source": "sdk_import",
3601
+ "priority": "high"
3602
+ },
3603
+ "billingAddress": {
3604
+ "country": "IN",
3605
+ "line1": "123 Main Street",
3606
+ "line2": "Apt 4B",
3607
+ "postalCode": "560001",
3608
+ "city": "Bangalore",
3609
+ "state": "Karnataka"
3610
+ },
3611
+ "createdOn": "2025-06-04T06:03:30.195790Z",
3612
+ "modifiedOn": "2025-06-04T06:03:30.195831Z"
3613
+ }
3614
+ ]
3615
+ }
3616
+ }
3617
+ }
3618
+ }
3619
+ }
3620
+ },
3085
3621
  "post": {
3086
3622
  "tags": [
3087
3623
  "Customers"
@@ -3089,6 +3625,9 @@
3089
3625
  "summary": "Create a customer",
3090
3626
  "description": "Creates a new customer record within kelviq.",
3091
3627
  "operationId": "createCustomer",
3628
+ "x-mint": {
3629
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
3630
+ },
3092
3631
  "requestBody": {
3093
3632
  "required": true,
3094
3633
  "content": {
@@ -3142,6 +3681,9 @@
3142
3681
  "summary": "Update a customer",
3143
3682
  "description": "Performs a partial update on an existing customer using their client-defined `customerId`.",
3144
3683
  "operationId": "updateCustomer",
3684
+ "x-mint": {
3685
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
3686
+ },
3145
3687
  "parameters": [
3146
3688
  {
3147
3689
  "name": "customerId",
@@ -3208,6 +3750,9 @@
3208
3750
  "summary": "Create a checkout session",
3209
3751
  "description": "Creates a new checkout session for a customer to proceed with a purchase or subscription.",
3210
3752
  "operationId": "createCheckoutSession",
3753
+ "x-mint": {
3754
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
3755
+ },
3211
3756
  "requestBody": {
3212
3757
  "required": true,
3213
3758
  "content": {
@@ -3239,8 +3784,12 @@
3239
3784
  "/entitlements/": {
3240
3785
  "servers": [
3241
3786
  {
3242
- "url": "https://edge.api.kelviq.com",
3243
- "description": "Edge API for Entitlements"
3787
+ "url": "https://edge.sandboxapi.kelviq.com/api/v1",
3788
+ "description": "Sandbox — Test environment"
3789
+ },
3790
+ {
3791
+ "url": "https://edge.api.kelviq.com/api/v1",
3792
+ "description": "Production — Live environment"
3244
3793
  }
3245
3794
  ],
3246
3795
  "get": {
@@ -3248,8 +3797,11 @@
3248
3797
  "Entitlements"
3249
3798
  ],
3250
3799
  "summary": "Retrieve customer entitlements",
3251
- "description": "Retrieves detailed entitlement information for a customer.\n- If `feature_idd` is provided as a query parameter, returns details for that specific feature.\n- If `feature_id` is omitted, returns all entitlements for the customer.\n",
3800
+ "description": "Retrieves detailed entitlement information for a customer.\n- If `feature_id` is provided as a query parameter, returns details for that specific feature.\n- If `feature_id` is omitted, returns all entitlements for the customer.\n",
3252
3801
  "operationId": "getCustomerEntitlements",
3802
+ "x-mint": {
3803
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
3804
+ },
3253
3805
  "parameters": [
3254
3806
  {
3255
3807
  "name": "customer_id",
@@ -3333,6 +3885,9 @@
3333
3885
  "/license/activate/": {
3334
3886
  "post": {
3335
3887
  "operationId": "licenseActivate",
3888
+ "x-mint": {
3889
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
3890
+ },
3336
3891
  "tags": [
3337
3892
  "License"
3338
3893
  ],
@@ -3469,6 +4024,9 @@
3469
4024
  "/license/deactivate/": {
3470
4025
  "post": {
3471
4026
  "operationId": "licenseDeactivate",
4027
+ "x-mint": {
4028
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4029
+ },
3472
4030
  "tags": [
3473
4031
  "License"
3474
4032
  ],
@@ -3533,6 +4091,9 @@
3533
4091
  "/license/validate/": {
3534
4092
  "post": {
3535
4093
  "operationId": "licenseValidate",
4094
+ "x-mint": {
4095
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4096
+ },
3536
4097
  "tags": [
3537
4098
  "License"
3538
4099
  ],
@@ -3660,6 +4221,9 @@
3660
4221
  "summary": "Report pre-aggregated usage",
3661
4222
  "description": "Reports pre-aggregated feature usage from your application to kelviq.",
3662
4223
  "operationId": "reportUsage",
4224
+ "x-mint": {
4225
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4226
+ },
3663
4227
  "requestBody": {
3664
4228
  "required": true,
3665
4229
  "content": {
@@ -3694,70 +4258,258 @@
3694
4258
  }
3695
4259
  }
3696
4260
  },
3697
- "/subscriptions/create/": {
4261
+ "/refunds/": {
4262
+ "get": {
4263
+ "tags": [
4264
+ "Refunds"
4265
+ ],
4266
+ "summary": "List refunds",
4267
+ "description": "Returns a paginated list of refunds for the authenticated organization, ordered newest first.",
4268
+ "operationId": "listRefunds",
4269
+ "x-mint": {
4270
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4271
+ },
4272
+ "parameters": [
4273
+ {
4274
+ "name": "search",
4275
+ "in": "query",
4276
+ "required": false,
4277
+ "description": "Search by refund ID, order ID, payment-provider refund ID, or customer name, email, or ID.",
4278
+ "schema": { "type": "string" }
4279
+ },
4280
+ {
4281
+ "name": "status",
4282
+ "in": "query",
4283
+ "required": false,
4284
+ "description": "Filter by refund status.",
4285
+ "schema": {
4286
+ "type": "string",
4287
+ "enum": ["PENDING", "PROCESSING", "SUCCEEDED", "FAILED", "CANCELED"]
4288
+ }
4289
+ },
4290
+ {
4291
+ "name": "start_date",
4292
+ "in": "query",
4293
+ "required": false,
4294
+ "description": "Include refunds created on or after this date.",
4295
+ "schema": { "type": "string", "format": "date" }
4296
+ },
4297
+ {
4298
+ "name": "end_date",
4299
+ "in": "query",
4300
+ "required": false,
4301
+ "description": "Include refunds created on or before this date.",
4302
+ "schema": { "type": "string", "format": "date" }
4303
+ },
4304
+ {
4305
+ "name": "page_size",
4306
+ "in": "query",
4307
+ "required": false,
4308
+ "description": "Number of results per page. Defaults to 10, maximum 100.",
4309
+ "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
4310
+ },
4311
+ {
4312
+ "name": "page",
4313
+ "in": "query",
4314
+ "required": false,
4315
+ "description": "Page number to return.",
4316
+ "schema": { "type": "integer", "minimum": 1 }
4317
+ }
4318
+ ],
4319
+ "responses": {
4320
+ "200": {
4321
+ "description": "A paginated list of refunds.",
4322
+ "content": {
4323
+ "application/json": {
4324
+ "schema": {
4325
+ "$ref": "#/components/schemas/RefundListResponse"
4326
+ }
4327
+ }
4328
+ }
4329
+ },
4330
+ "401": {
4331
+ "description": "Unauthorized — missing or invalid API key."
4332
+ }
4333
+ }
4334
+ },
3698
4335
  "post": {
3699
4336
  "tags": [
3700
- "Subscriptions"
4337
+ "Refunds"
3701
4338
  ],
3702
- "summary": "Create a subscription",
3703
- "description": "Creates a new subscription for a customer directly, without requiring a checkout session.",
3704
- "operationId": "createSubscription",
4339
+ "summary": "Create a refund",
4340
+ "description": "Creates a full or partial refund for an order owned by the authenticated organization. Specify either `amountUnits` or `amount` for a partial refund; omit both to refund the entire remaining refundable balance. The amount must be positive and cannot exceed the order's remaining refundable balance.",
4341
+ "operationId": "createRefund",
4342
+ "x-mint": {
4343
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4344
+ },
4345
+ "requestBody": {
4346
+ "required": true,
4347
+ "content": {
4348
+ "application/json": {
4349
+ "schema": {
4350
+ "$ref": "#/components/schemas/RefundCreateRequest"
4351
+ },
4352
+ "examples": {
4353
+ "partialRefund": {
4354
+ "summary": "Partial refund",
4355
+ "value": {
4356
+ "orderId": "ORD-20260715123000-A1B2C",
4357
+ "amountUnits": 2500,
4358
+ "reason": "REQUESTED_BY_CUSTOMER",
4359
+ "internalNote": "Customer requested a partial refund."
4360
+ }
4361
+ },
4362
+ "fullRefund": {
4363
+ "summary": "Full refund of the remaining balance",
4364
+ "value": {
4365
+ "orderId": "ORD-20260715123000-A1B2C"
4366
+ }
4367
+ }
4368
+ }
4369
+ }
4370
+ }
4371
+ },
4372
+ "responses": {
4373
+ "200": {
4374
+ "description": "Refund initiated. The returned status reflects the payment provider's current result.",
4375
+ "content": {
4376
+ "application/json": {
4377
+ "schema": {
4378
+ "$ref": "#/components/schemas/RefundResponse"
4379
+ }
4380
+ }
4381
+ }
4382
+ },
4383
+ "400": {
4384
+ "description": "Invalid amount or reason, insufficient refundable balance, or a payment-provider error.",
4385
+ "content": {
4386
+ "application/json": {
4387
+ "schema": {
4388
+ "$ref": "#/components/schemas/RefundErrorResponse"
4389
+ }
4390
+ }
4391
+ }
4392
+ },
4393
+ "401": {
4394
+ "description": "Unauthorized — missing or invalid API key."
4395
+ },
4396
+ "404": {
4397
+ "description": "Order not found for the authenticated organization."
4398
+ }
4399
+ }
4400
+ }
4401
+ },
4402
+ "/refunds/{refundId}/": {
4403
+ "get": {
4404
+ "tags": [
4405
+ "Refunds"
4406
+ ],
4407
+ "summary": "Retrieve a refund",
4408
+ "description": "Returns a refund owned by the authenticated organization.",
4409
+ "operationId": "retrieveRefund",
4410
+ "x-mint": {
4411
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4412
+ },
4413
+ "parameters": [
4414
+ {
4415
+ "name": "refundId",
4416
+ "in": "path",
4417
+ "required": true,
4418
+ "description": "The UUID of the refund.",
4419
+ "schema": {
4420
+ "type": "string",
4421
+ "format": "uuid"
4422
+ },
4423
+ "example": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11"
4424
+ }
4425
+ ],
4426
+ "responses": {
4427
+ "200": {
4428
+ "description": "Refund details.",
4429
+ "content": {
4430
+ "application/json": {
4431
+ "schema": {
4432
+ "$ref": "#/components/schemas/RefundResponse"
4433
+ }
4434
+ }
4435
+ }
4436
+ },
4437
+ "401": {
4438
+ "description": "Unauthorized — missing or invalid API key."
4439
+ },
4440
+ "404": {
4441
+ "description": "Refund not found for the authenticated organization."
4442
+ }
4443
+ }
4444
+ }
4445
+ },
4446
+ "/charges/": {
4447
+ "post": {
4448
+ "tags": [
4449
+ "Charges"
4450
+ ],
4451
+ "summary": "Create a charge",
4452
+ "description": "Creates a one-time charge billed immediately against the customer's default payment method, without requiring a checkout session.\n\nThe customer must already have a usable payment method on file (a saved payment method or an active subscription). If no default payment method exists, or the off-session charge is declined or requires authentication, the request fails with a `400`.\n\n> **Note:** `chargePeriod` must be `ONE_TIME`. Recurring charge periods are not supported by this endpoint — use [Create a subscription](/api-reference/subscriptions/create-a-subscription) instead.",
4453
+ "operationId": "createCharge",
4454
+ "x-mint": {
4455
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4456
+ },
3705
4457
  "requestBody": {
3706
4458
  "required": true,
3707
4459
  "content": {
3708
4460
  "application/json": {
3709
4461
  "schema": {
3710
- "$ref": "#/components/schemas/CreateSubscriptionRequest"
4462
+ "$ref": "#/components/schemas/CreateChargeRequest"
3711
4463
  }
3712
4464
  }
3713
4465
  }
3714
4466
  },
3715
4467
  "responses": {
3716
4468
  "201": {
3717
- "description": "Subscription Created",
4469
+ "description": "Charge created",
3718
4470
  "content": {
3719
4471
  "application/json": {
3720
4472
  "schema": {
3721
- "$ref": "#/components/schemas/CreateSubscriptionResponse"
4473
+ "$ref": "#/components/schemas/CreateChargeResponse"
3722
4474
  },
3723
4475
  "example": {
3724
- "id": "520ca8a5-9fc0-4d6a-bc7a-2ba331595441",
3725
- "startDate": "2026-02-07",
4476
+ "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
4477
+ "startDate": "2026-06-20",
3726
4478
  "endDate": null,
3727
- "billingPeriodStartTime": "2026-02-07T06:02:05Z",
3728
- "billingPeriodEndTime": "2026-02-08T06:02:05Z",
3729
- "amount": "2000.00",
3730
- "recurrence": "month",
4479
+ "billingPeriodStartTime": null,
4480
+ "billingPeriodEndTime": null,
4481
+ "amount": "49.00",
4482
+ "recurrence": "",
3731
4483
  "currency": "USD",
3732
- "status": "trialing",
4484
+ "status": "active",
3733
4485
  "product": {
3734
4486
  "name": "Invoice Test",
3735
4487
  "id": "88e437b8-6017-405b-9328-e0f4e140bb79",
3736
4488
  "identifier": "invoice-test"
3737
4489
  },
3738
4490
  "plan": {
3739
- "name": "iUltra",
3740
- "identifier": "i-ultra"
4491
+ "name": "Lifetime Access",
4492
+ "identifier": "lifetime-access"
3741
4493
  },
3742
4494
  "features": [],
3743
- "trialDaysRemaining": 1,
4495
+ "trialDaysRemaining": 0,
3744
4496
  "customerId": "geojacob",
3745
- "billingType": "SUBSCRIPTION",
3746
- "recurrenceUnit": 1,
3747
- "recurrenceType": "MONTH"
4497
+ "billingType": "ONE_TIME",
4498
+ "recurrenceUnit": null,
4499
+ "recurrenceType": null
3748
4500
  }
3749
4501
  }
3750
4502
  }
3751
4503
  },
3752
4504
  "400": {
3753
- "description": "Bad Request - Validation or business logic error.",
4505
+ "description": "Bad Request - Validation or business logic error (e.g. no default payment method, declined charge, blocked organization, or a non-`ONE_TIME` charge period).",
3754
4506
  "content": {
3755
4507
  "application/json": {
3756
4508
  "schema": {
3757
4509
  "$ref": "#/components/schemas/DetailErrorResponse"
3758
4510
  },
3759
4511
  "example": {
3760
- "detail": "Customer does not exist."
4512
+ "detail": "A payment method is required to complete this payment."
3761
4513
  }
3762
4514
  }
3763
4515
  }
@@ -3771,14 +4523,17 @@
3771
4523
  "Subscriptions"
3772
4524
  ],
3773
4525
  "summary": "List Subscriptions",
3774
- "description": "Retrieves a paginated list of subscriptions. You can filter the results by customer.",
4526
+ "description": "Retrieves a paginated list of subscriptions for a customer.",
3775
4527
  "operationId": "listSubscriptions",
4528
+ "x-mint": {
4529
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4530
+ },
3776
4531
  "parameters": [
3777
4532
  {
3778
4533
  "name": "customer_id",
3779
4534
  "in": "query",
3780
- "required": false,
3781
- "description": "The client-defined unique identifier for the customer to filter subscriptions.",
4535
+ "required": true,
4536
+ "description": "The client-defined unique identifier of the customer whose subscriptions will be returned.",
3782
4537
  "schema": {
3783
4538
  "type": "string"
3784
4539
  }
@@ -3787,9 +4542,11 @@
3787
4542
  "name": "page_size",
3788
4543
  "in": "query",
3789
4544
  "required": false,
3790
- "description": "Number of results to return per page.",
4545
+ "description": "Number of results to return per page. Defaults to 10, maximum 100.",
3791
4546
  "schema": {
3792
- "type": "integer"
4547
+ "type": "integer",
4548
+ "minimum": 1,
4549
+ "maximum": 100
3793
4550
  }
3794
4551
  },
3795
4552
  {
@@ -3859,12 +4616,241 @@
3859
4616
  "customerId": "testuser",
3860
4617
  "billingType": "SUBSCRIPTION",
3861
4618
  "recurrenceUnit": 1,
3862
- "recurrenceType": "MONTH"
4619
+ "recurrenceType": "MONTH",
4620
+ "files": [
4621
+ {
4622
+ "id": "bf9f0fe0-c9c0-436d-8811-e412d0365470",
4623
+ "name": "custom-pricinig.png",
4624
+ "file": "https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png",
4625
+ "ordering": 0,
4626
+ "enabled": true,
4627
+ "downloadUrl": "https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/"
4628
+ }
4629
+ ],
4630
+ "links": [
4631
+ {
4632
+ "name": "Product documentation",
4633
+ "url": "https://example.com/docs"
4634
+ }
4635
+ ],
4636
+ "license": [
4637
+ {
4638
+ "id": "f81efb90-5f29-4dd1-9c7b-be4085e473de",
4639
+ "licenseKey": "10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1",
4640
+ "activatedOn": null,
4641
+ "expiresOn": null,
4642
+ "activationUsage": 0,
4643
+ "activationLimit": 2,
4644
+ "enabled": true
4645
+ }
4646
+ ]
4647
+ }
4648
+ ]
4649
+ }
4650
+ }
4651
+ }
4652
+ }
4653
+ }
4654
+ }
4655
+ },
4656
+ "/subscriptions/create/": {
4657
+ "post": {
4658
+ "tags": [
4659
+ "Subscriptions"
4660
+ ],
4661
+ "summary": "Create a subscription",
4662
+ "description": "Creates a new subscription for a customer directly, without requiring a checkout session.",
4663
+ "operationId": "createSubscription",
4664
+ "x-mint": {
4665
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4666
+ },
4667
+ "requestBody": {
4668
+ "required": true,
4669
+ "content": {
4670
+ "application/json": {
4671
+ "schema": {
4672
+ "$ref": "#/components/schemas/CreateSubscriptionRequest"
4673
+ }
4674
+ }
4675
+ }
4676
+ },
4677
+ "responses": {
4678
+ "201": {
4679
+ "description": "Subscription Created",
4680
+ "content": {
4681
+ "application/json": {
4682
+ "schema": {
4683
+ "$ref": "#/components/schemas/CreateSubscriptionResponse"
4684
+ },
4685
+ "example": {
4686
+ "id": "520ca8a5-9fc0-4d6a-bc7a-2ba331595441",
4687
+ "startDate": "2026-02-07",
4688
+ "endDate": null,
4689
+ "billingPeriodStartTime": "2026-02-07T06:02:05Z",
4690
+ "billingPeriodEndTime": "2026-02-08T06:02:05Z",
4691
+ "amount": "2000.00",
4692
+ "recurrence": "month",
4693
+ "currency": "USD",
4694
+ "status": "trialing",
4695
+ "product": {
4696
+ "name": "Invoice Test",
4697
+ "id": "88e437b8-6017-405b-9328-e0f4e140bb79",
4698
+ "identifier": "invoice-test"
4699
+ },
4700
+ "plan": {
4701
+ "name": "iUltra",
4702
+ "identifier": "i-ultra"
4703
+ },
4704
+ "features": [],
4705
+ "trialDaysRemaining": 1,
4706
+ "customerId": "geojacob",
4707
+ "billingType": "SUBSCRIPTION",
4708
+ "recurrenceUnit": 1,
4709
+ "recurrenceType": "MONTH",
4710
+ "files": [
4711
+ {
4712
+ "id": "bf9f0fe0-c9c0-436d-8811-e412d0365470",
4713
+ "name": "custom-pricinig.png",
4714
+ "file": "https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png",
4715
+ "ordering": 0,
4716
+ "enabled": true,
4717
+ "downloadUrl": "https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/"
4718
+ }
4719
+ ],
4720
+ "links": [
4721
+ {
4722
+ "name": "Product documentation",
4723
+ "url": "https://example.com/docs"
4724
+ }
4725
+ ],
4726
+ "license": [
4727
+ {
4728
+ "id": "f81efb90-5f29-4dd1-9c7b-be4085e473de",
4729
+ "licenseKey": "10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1",
4730
+ "activatedOn": null,
4731
+ "expiresOn": null,
4732
+ "activationUsage": 0,
4733
+ "activationLimit": 2,
4734
+ "enabled": true
4735
+ }
4736
+ ]
4737
+ }
4738
+ }
4739
+ }
4740
+ },
4741
+ "400": {
4742
+ "description": "Bad Request - Validation or business logic error.",
4743
+ "content": {
4744
+ "application/json": {
4745
+ "schema": {
4746
+ "$ref": "#/components/schemas/DetailErrorResponse"
4747
+ },
4748
+ "example": {
4749
+ "detail": "Customer does not exist."
4750
+ }
4751
+ }
4752
+ }
4753
+ }
4754
+ }
4755
+ }
4756
+ },
4757
+ "/subscriptions/{subscriptionId}/": {
4758
+ "get": {
4759
+ "tags": [
4760
+ "Subscriptions"
4761
+ ],
4762
+ "summary": "Retrieve a Subscription",
4763
+ "description": "Retrieves a subscription by its Kelviq subscription ID.",
4764
+ "operationId": "retrieveSubscription",
4765
+ "x-mint": {
4766
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4767
+ },
4768
+ "parameters": [
4769
+ {
4770
+ "name": "subscriptionId",
4771
+ "in": "path",
4772
+ "required": true,
4773
+ "description": "The unique Kelviq identifier of the subscription.",
4774
+ "example": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
4775
+ "schema": {
4776
+ "type": "string",
4777
+ "format": "uuid"
4778
+ }
4779
+ }
4780
+ ],
4781
+ "responses": {
4782
+ "200": {
4783
+ "description": "Subscription details.",
4784
+ "content": {
4785
+ "application/json": {
4786
+ "schema": {
4787
+ "$ref": "#/components/schemas/Subscription"
4788
+ },
4789
+ "example": {
4790
+ "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
4791
+ "externalSubscriptionId": "sub_1RpoZoSBstCzyocS7iPmith3",
4792
+ "startDate": "2025-07-28",
4793
+ "endDate": null,
4794
+ "billingPeriodStartTime": "2025-07-28T10:46:34Z",
4795
+ "billingPeriodEndTime": "2025-08-28T10:46:34Z",
4796
+ "amount": "261.00",
4797
+ "recurrence": "month",
4798
+ "currency": "usd",
4799
+ "status": "active",
4800
+ "product": "Aphelo",
4801
+ "plan": {
4802
+ "name": "Premium",
4803
+ "identifier": "premium1"
4804
+ },
4805
+ "features": [],
4806
+ "trialDaysRemaining": 0,
4807
+ "customerId": "testuser",
4808
+ "billingType": "SUBSCRIPTION",
4809
+ "recurrenceUnit": 1,
4810
+ "recurrenceType": "MONTH",
4811
+ "files": [
4812
+ {
4813
+ "id": "bf9f0fe0-c9c0-436d-8811-e412d0365470",
4814
+ "name": "custom-pricinig.png",
4815
+ "file": "https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png",
4816
+ "ordering": 0,
4817
+ "enabled": true,
4818
+ "downloadUrl": "https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/"
4819
+ }
4820
+ ],
4821
+ "links": [
4822
+ {
4823
+ "name": "Product documentation",
4824
+ "url": "https://example.com/docs"
4825
+ }
4826
+ ],
4827
+ "license": [
4828
+ {
4829
+ "id": "f81efb90-5f29-4dd1-9c7b-be4085e473de",
4830
+ "licenseKey": "10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1",
4831
+ "activatedOn": null,
4832
+ "expiresOn": null,
4833
+ "activationUsage": 0,
4834
+ "activationLimit": 2,
4835
+ "enabled": true
3863
4836
  }
3864
4837
  ]
3865
4838
  }
3866
4839
  }
3867
4840
  }
4841
+ },
4842
+ "404": {
4843
+ "description": "Subscription not found.",
4844
+ "content": {
4845
+ "application/json": {
4846
+ "schema": {
4847
+ "$ref": "#/components/schemas/DetailErrorResponse"
4848
+ },
4849
+ "example": {
4850
+ "detail": "Subscription not found."
4851
+ }
4852
+ }
4853
+ }
3868
4854
  }
3869
4855
  }
3870
4856
  }
@@ -3875,8 +4861,11 @@
3875
4861
  "Subscriptions"
3876
4862
  ],
3877
4863
  "summary": "Update a subscription",
3878
- "description": "Updates an existing subscription to a new plan, charge period, and/or features.\n\n> **Warning:** Free plans are created as one-time charges. Upgrading from a free plan is not supported via this endpoint. Use the [Create Checkout Session](/api-reference/checkout/create-a-checkout-session) endpoint instead.",
4864
+ "description": "Updates an existing subscription to a new plan, charge period, and/or features. Set `paymentBehavior` to `activate_on_payment` when the change should take effect only after payment succeeds.\n\n> **Warning:** Free plans are created as one-time charges. Upgrading from a free plan is not supported via this endpoint. Use the [Create Checkout Session](/api-reference/checkout/create-a-checkout-session) endpoint instead.",
3879
4865
  "operationId": "updateSubscription",
4866
+ "x-mint": {
4867
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4868
+ },
3880
4869
  "parameters": [
3881
4870
  {
3882
4871
  "name": "subscriptionId",
@@ -3925,6 +4914,9 @@
3925
4914
  "summary": "Cancel a subscription",
3926
4915
  "description": "Cancels an active subscription for a customer.",
3927
4916
  "operationId": "cancelSubscription",
4917
+ "x-mint": {
4918
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4919
+ },
3928
4920
  "parameters": [
3929
4921
  {
3930
4922
  "name": "subscriptionId",
@@ -3973,6 +4965,9 @@
3973
4965
  "summary": "Get Product Offering",
3974
4966
  "description": "Retrieves the public pricing details for a specific product, including all eligible plans, localized pricing, and the customer's current subscription state. Use this to render a pricing page or paywall scoped to a product.",
3975
4967
  "operationId": "getProductOffering",
4968
+ "x-mint": {
4969
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
4970
+ },
3976
4971
  "parameters": [
3977
4972
  {
3978
4973
  "name": "product_id",
@@ -4002,6 +4997,16 @@
4002
4997
  "type": "string"
4003
4998
  },
4004
4999
  "example": "pro,enterprise"
5000
+ },
5001
+ {
5002
+ "name": "ip_address",
5003
+ "in": "query",
5004
+ "required": false,
5005
+ "description": "Optional. The end customer's IP address, used to determine pricing locale and currency based on their location. Only applied when authenticating with a server API key.",
5006
+ "schema": {
5007
+ "type": "string"
5008
+ },
5009
+ "example": "203.0.113.42"
4005
5010
  }
4006
5011
  ],
4007
5012
  "responses": {
@@ -4290,10 +5295,17 @@
4290
5295
  "summary": "Get promotions",
4291
5296
  "description": "Resolves the active promotion for the caller's detected location. Returns the applicable discount percentage, coupon code, banner widget configuration, and security check results.\n\n<Warning>Use your **Client API Key**, not your Server API Key. Find it under **Settings \u2192 API keys** in the Kelviq dashboard.</Warning>",
4292
5297
  "operationId": "getPromotion",
5298
+ "x-mint": {
5299
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5300
+ },
4293
5301
  "servers": [
4294
5302
  {
4295
- "url": "https://edge.kelviq.com/api/v1",
4296
- "description": "Kelviq Edge API"
5303
+ "url": "https://edge.sandboxapi.kelviq.com/api/v1",
5304
+ "description": "Sandbox — Test environment"
5305
+ },
5306
+ {
5307
+ "url": "https://edge.api.kelviq.com/api/v1",
5308
+ "description": "Production — Live environment"
4297
5309
  }
4298
5310
  ],
4299
5311
  "parameters": [
@@ -4369,6 +5381,9 @@
4369
5381
  "summary": "Create a portal session",
4370
5382
  "description": "Creates a new customer portal session, returning a token and URL to redirect the customer to their billing portal.",
4371
5383
  "operationId": "createPortalSession",
5384
+ "x-mint": {
5385
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5386
+ },
4372
5387
  "security": [
4373
5388
  {
4374
5389
  "bearerAuth": []
@@ -4412,6 +5427,9 @@
4412
5427
  "summary": "List products",
4413
5428
  "description": "Returns a paginated list of all products in the organization's catalog. Archived products are excluded.",
4414
5429
  "operationId": "listCatalogProducts",
5430
+ "x-mint": {
5431
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5432
+ },
4415
5433
  "security": [{ "bearerAuth": [] }],
4416
5434
  "parameters": [
4417
5435
  {
@@ -4429,6 +5447,13 @@
4429
5447
  "description": "Page number for pagination.",
4430
5448
  "example": 1,
4431
5449
  "schema": { "type": "integer" }
5450
+ },
5451
+ {
5452
+ "name": "page_size",
5453
+ "in": "query",
5454
+ "required": false,
5455
+ "description": "Number of results per page. Defaults to 100, maximum 100.",
5456
+ "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
4432
5457
  }
4433
5458
  ],
4434
5459
  "responses": {
@@ -4448,6 +5473,9 @@
4448
5473
  "summary": "Create a product",
4449
5474
  "description": "Creates a new product.",
4450
5475
  "operationId": "createCatalogProduct",
5476
+ "x-mint": {
5477
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5478
+ },
4451
5479
  "security": [{ "bearerAuth": [] }],
4452
5480
  "requestBody": {
4453
5481
  "required": true,
@@ -4505,6 +5533,9 @@
4505
5533
  "summary": "Retrieve a product",
4506
5534
  "description": "Fetches a product by ID along with its currently published plans.",
4507
5535
  "operationId": "retrieveCatalogProduct",
5536
+ "x-mint": {
5537
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5538
+ },
4508
5539
  "security": [{ "bearerAuth": [] }],
4509
5540
  "responses": {
4510
5541
  "200": {
@@ -4524,6 +5555,9 @@
4524
5555
  "summary": "Update a product",
4525
5556
  "description": "Partially updates a product. New images and files can be attached by sending temporary S3 keys in `imageKeys` / `fileKeys`.",
4526
5557
  "operationId": "updateCatalogProduct",
5558
+ "x-mint": {
5559
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5560
+ },
4527
5561
  "security": [{ "bearerAuth": [] }],
4528
5562
  "requestBody": {
4529
5563
  "required": true,
@@ -4550,6 +5584,9 @@
4550
5584
  "summary": "Archive a product",
4551
5585
  "description": "Soft-deletes (archives) the product. Already-archived products return 400.",
4552
5586
  "operationId": "deleteCatalogProduct",
5587
+ "x-mint": {
5588
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5589
+ },
4553
5590
  "security": [{ "bearerAuth": [] }],
4554
5591
  "responses": {
4555
5592
  "204": {
@@ -4582,6 +5619,9 @@
4582
5619
  "summary": "Retrieve product settings",
4583
5620
  "description": "Retrieves the VPN/TOR/proxy and presentation settings for a product. Settings are auto-created if they don't already exist.",
4584
5621
  "operationId": "getCatalogProductSettings",
5622
+ "x-mint": {
5623
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5624
+ },
4585
5625
  "security": [{ "bearerAuth": [] }],
4586
5626
  "responses": {
4587
5627
  "200": {
@@ -4600,6 +5640,9 @@
4600
5640
  "summary": "Update product settings",
4601
5641
  "description": "Updates one or more product settings fields. Changing `currency` re-enables previously disabled prices in the new currency on the latest plans of that product.",
4602
5642
  "operationId": "updateCatalogProductSettings",
5643
+ "x-mint": {
5644
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5645
+ },
4603
5646
  "security": [{ "bearerAuth": [] }],
4604
5647
  "requestBody": {
4605
5648
  "required": true,
@@ -4646,6 +5689,9 @@
4646
5689
  "summary": "Update a product image",
4647
5690
  "description": "Updates image metadata such as `name`, `ordering`, `thumbnail`, or `enabled`. Setting `thumbnail` to true automatically clears the flag on the product's other images.",
4648
5691
  "operationId": "updateCatalogProductImage",
5692
+ "x-mint": {
5693
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5694
+ },
4649
5695
  "security": [{ "bearerAuth": [] }],
4650
5696
  "requestBody": {
4651
5697
  "required": true,
@@ -4672,6 +5718,9 @@
4672
5718
  "summary": "Delete a product image",
4673
5719
  "description": "Permanently deletes the product image record.",
4674
5720
  "operationId": "deleteCatalogProductImage",
5721
+ "x-mint": {
5722
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5723
+ },
4675
5724
  "security": [{ "bearerAuth": [] }],
4676
5725
  "responses": {
4677
5726
  "204": { "description": "Image deleted." },
@@ -4686,6 +5735,9 @@
4686
5735
  "summary": "List features",
4687
5736
  "description": "Returns a paginated list of features for the organization. Archived features are excluded.",
4688
5737
  "operationId": "listCatalogFeatures",
5738
+ "x-mint": {
5739
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5740
+ },
4689
5741
  "security": [{ "bearerAuth": [] }],
4690
5742
  "parameters": [
4691
5743
  {
@@ -4695,6 +5747,21 @@
4695
5747
  "description": "Free-text search across `name`, `identifier`, and `description`.",
4696
5748
  "example": "api",
4697
5749
  "schema": { "type": "string" }
5750
+ },
5751
+ {
5752
+ "name": "page",
5753
+ "in": "query",
5754
+ "required": false,
5755
+ "description": "Page number for pagination.",
5756
+ "example": 1,
5757
+ "schema": { "type": "integer", "minimum": 1 }
5758
+ },
5759
+ {
5760
+ "name": "page_size",
5761
+ "in": "query",
5762
+ "required": false,
5763
+ "description": "Number of results per page. Defaults to 100, maximum 100.",
5764
+ "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
4698
5765
  }
4699
5766
  ],
4700
5767
  "responses": {
@@ -4714,6 +5781,9 @@
4714
5781
  "summary": "Create a feature",
4715
5782
  "description": "Creates a new feature. For METER features, `featureDetails` must include a `featureSubType` (PRE_AGGREGATED_USAGE or RAW_EVENTS) and `units`. RAW_EVENTS additionally requires a `meter` object with `aggregation` and `filters`.",
4716
5783
  "operationId": "createCatalogFeature",
5784
+ "x-mint": {
5785
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5786
+ },
4717
5787
  "security": [{ "bearerAuth": [] }],
4718
5788
  "requestBody": {
4719
5789
  "required": true,
@@ -4751,6 +5821,9 @@
4751
5821
  "tags": ["Features"],
4752
5822
  "summary": "Retrieve a feature",
4753
5823
  "operationId": "retrieveCatalogFeature",
5824
+ "x-mint": {
5825
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5826
+ },
4754
5827
  "security": [{ "bearerAuth": [] }],
4755
5828
  "responses": {
4756
5829
  "200": {
@@ -4770,6 +5843,9 @@
4770
5843
  "summary": "Archive a feature",
4771
5844
  "description": "Soft-deletes the feature and updates any published pricing tables that referenced it.",
4772
5845
  "operationId": "deleteCatalogFeature",
5846
+ "x-mint": {
5847
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5848
+ },
4773
5849
  "security": [{ "bearerAuth": [] }],
4774
5850
  "responses": {
4775
5851
  "204": {
@@ -4792,7 +5868,27 @@
4792
5868
  "summary": "List plans",
4793
5869
  "description": "Returns one row per plan identifier, picking the most recent version for each. Archived plans, or plans on archived products, are excluded.",
4794
5870
  "operationId": "listCatalogPlans",
5871
+ "x-mint": {
5872
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5873
+ },
4795
5874
  "security": [{ "bearerAuth": [] }],
5875
+ "parameters": [
5876
+ {
5877
+ "name": "page",
5878
+ "in": "query",
5879
+ "required": false,
5880
+ "description": "Page number for pagination.",
5881
+ "example": 1,
5882
+ "schema": { "type": "integer", "minimum": 1 }
5883
+ },
5884
+ {
5885
+ "name": "page_size",
5886
+ "in": "query",
5887
+ "required": false,
5888
+ "description": "Number of results per page. Defaults to 100, maximum 100.",
5889
+ "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
5890
+ }
5891
+ ],
4796
5892
  "responses": {
4797
5893
  "200": {
4798
5894
  "description": "Paginated list of plans.",
@@ -4810,6 +5906,9 @@
4810
5906
  "summary": "Create a plan",
4811
5907
  "description": "Creates a new plan against a product. The new plan starts as an unpublished draft (`isLatest=false`) until `POST /plans/{identifier}/publish/` is called.",
4812
5908
  "operationId": "createCatalogPlan",
5909
+ "x-mint": {
5910
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5911
+ },
4813
5912
  "security": [{ "bearerAuth": [] }],
4814
5913
  "requestBody": {
4815
5914
  "required": true,
@@ -4856,6 +5955,9 @@
4856
5955
  "summary": "Retrieve a plan",
4857
5956
  "description": "Fetches a plan by identifier. Pass `?version=N` to fetch a specific version; otherwise the latest version is returned.",
4858
5957
  "operationId": "retrieveCatalogPlan",
5958
+ "x-mint": {
5959
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5960
+ },
4859
5961
  "security": [{ "bearerAuth": [] }],
4860
5962
  "responses": {
4861
5963
  "200": {
@@ -4875,6 +5977,9 @@
4875
5977
  "summary": "Update a plan",
4876
5978
  "description": "Partial update. If the latest version is already published (`isLatest=true`), a new draft version is created automatically; otherwise the existing draft is mutated.",
4877
5979
  "operationId": "updateCatalogPlan",
5980
+ "x-mint": {
5981
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
5982
+ },
4878
5983
  "security": [{ "bearerAuth": [] }],
4879
5984
  "requestBody": {
4880
5985
  "required": true,
@@ -4901,6 +6006,9 @@
4901
6006
  "summary": "Archive a plan",
4902
6007
  "description": "Archives all versions of the plan (sets `isArchived=true`).",
4903
6008
  "operationId": "deleteCatalogPlan",
6009
+ "x-mint": {
6010
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6011
+ },
4904
6012
  "security": [{ "bearerAuth": [] }],
4905
6013
  "responses": {
4906
6014
  "204": {
@@ -4933,6 +6041,9 @@
4933
6041
  "summary": "Publish a plan",
4934
6042
  "description": "Promotes the most recent draft version of the plan to `isLatest=true`, demotes the previous published version, and syncs the plan to Stripe / internal billing. Optionally migrates existing customers' features or pricing. Fails with 400 if no price exists or required currencies are missing.",
4935
6043
  "operationId": "publishCatalogPlan",
6044
+ "x-mint": {
6045
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6046
+ },
4936
6047
  "security": [{ "bearerAuth": [] }],
4937
6048
  "requestBody": {
4938
6049
  "required": false,
@@ -4974,6 +6085,9 @@
4974
6085
  "summary": "Discard draft plan",
4975
6086
  "description": "Permanently deletes the latest draft (non-published) version of the plan. The previously published version remains untouched. Returns 400 if the latest version is already published.",
4976
6087
  "operationId": "discardCatalogPlanDraft",
6088
+ "x-mint": {
6089
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6090
+ },
4977
6091
  "security": [{ "bearerAuth": [] }],
4978
6092
  "responses": {
4979
6093
  "204": {
@@ -5014,6 +6128,9 @@
5014
6128
  "summary": "List plan prices",
5015
6129
  "description": "Returns the prices configured on the plan (one per currency), each with its full per-feature charge configuration.",
5016
6130
  "operationId": "listCatalogPlanPrices",
6131
+ "x-mint": {
6132
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6133
+ },
5017
6134
  "security": [{ "bearerAuth": [] }],
5018
6135
  "responses": {
5019
6136
  "200": {
@@ -5044,6 +6161,9 @@
5044
6161
  "summary": "Update plan prices",
5045
6162
  "description": "Atomically replaces the plan's prices with the supplied list. If the plan's latest version is published, a new draft version is created and the new prices are attached to it. Duplicate currencies among PAID prices are rejected.",
5046
6163
  "operationId": "bulkSetCatalogPlanPrices",
6164
+ "x-mint": {
6165
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6166
+ },
5047
6167
  "security": [{ "bearerAuth": [] }],
5048
6168
  "requestBody": {
5049
6169
  "required": true,
@@ -5091,6 +6211,9 @@
5091
6211
  "summary": "List plan entitlements",
5092
6212
  "description": "Returns the feature entitlements (with per-entitlement `details`) configured on the plan.",
5093
6213
  "operationId": "listCatalogPlanFeatures",
6214
+ "x-mint": {
6215
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6216
+ },
5094
6217
  "security": [{ "bearerAuth": [] }],
5095
6218
  "responses": {
5096
6219
  "200": {
@@ -5109,6 +6232,9 @@
5109
6232
  "summary": "Add plan entitlements",
5110
6233
  "description": "Appends one or more feature entitlements to the plan. If the plan's latest version is published, a new draft version is created automatically.",
5111
6234
  "operationId": "addCatalogPlanFeatures",
6235
+ "x-mint": {
6236
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6237
+ },
5112
6238
  "security": [{ "bearerAuth": [] }],
5113
6239
  "requestBody": {
5114
6240
  "required": true,
@@ -5155,6 +6281,9 @@
5155
6281
  "summary": "Update plan entitlement",
5156
6282
  "description": "Updates only the `details` (value, reset, hardLimit, rollover, etc.) of one feature entitlement on the plan. A new draft version is created if the latest is published.",
5157
6283
  "operationId": "updateCatalogPlanFeature",
6284
+ "x-mint": {
6285
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6286
+ },
5158
6287
  "security": [{ "bearerAuth": [] }],
5159
6288
  "requestBody": {
5160
6289
  "required": true,
@@ -5181,6 +6310,9 @@
5181
6310
  "summary": "Delete plan entitlement",
5182
6311
  "description": "Removes the named feature from the plan's entitlements. A new draft version is created if the latest is published.",
5183
6312
  "operationId": "deleteCatalogPlanFeature",
6313
+ "x-mint": {
6314
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6315
+ },
5184
6316
  "security": [{ "bearerAuth": [] }],
5185
6317
  "responses": {
5186
6318
  "204": {
@@ -5220,6 +6352,9 @@
5220
6352
  "summary": "Update a plan file",
5221
6353
  "description": "Updates display metadata on a plan file (name, ordering, enabled). If the plan's latest version is published, a new draft version is created and the file is updated on the new draft.",
5222
6354
  "operationId": "updateCatalogPlanFile",
6355
+ "x-mint": {
6356
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6357
+ },
5223
6358
  "security": [{ "bearerAuth": [] }],
5224
6359
  "requestBody": {
5225
6360
  "required": true,
@@ -5247,6 +6382,9 @@
5247
6382
  "summary": "Delete a plan file",
5248
6383
  "description": "Deletes the plan file. If the plan's latest version is published, a new draft version is created and the file is removed from the new draft.",
5249
6384
  "operationId": "deleteCatalogPlanFile",
6385
+ "x-mint": {
6386
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6387
+ },
5250
6388
  "security": [{ "bearerAuth": [] }],
5251
6389
  "responses": {
5252
6390
  "204": { "description": "File deleted." },
@@ -5278,6 +6416,9 @@
5278
6416
  "summary": "Download a plan file",
5279
6417
  "description": "Public download endpoint for a plan file. Responds with a 302 redirect to a short-lived forced-download URL on the storage backend. Returns 404 if the file does not exist.",
5280
6418
  "operationId": "downloadCatalogPlanFile",
6419
+ "x-mint": {
6420
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6421
+ },
5281
6422
  "security": [],
5282
6423
  "responses": {
5283
6424
  "302": {
@@ -5299,6 +6440,9 @@
5299
6440
  "summary": "Generate a presigned upload URL",
5300
6441
  "description": "Returns a presigned S3 POST policy that lets you upload a single file directly to kelviq's storage bucket (max 5 GB, expires in 1 hour). Use the returned `fileKey` as the value of `imageKeys` / `fileKeys` on the catalog product/plan endpoints.\n\nUpload flow:\n1. `POST /media/` with `fileName` and `fileType`.\n2. Build a `multipart/form-data` request and send every key/value from `fields` as a form field, plus a final `file` field containing the binary.\n3. `POST` that form to the returned `url`. A `204 No Content` response means the upload succeeded.\n4. Pass `fileKey` to the relevant catalog endpoint (e.g. `POST /catalog/products/` with `imageKeys: [fileKey]`).",
5301
6442
  "operationId": "createPresignedUploadUrl",
6443
+ "x-mint": {
6444
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6445
+ },
5302
6446
  "security": [{ "bearerAuth": [] }],
5303
6447
  "requestBody": {
5304
6448
  "required": true,
@@ -5340,6 +6484,9 @@
5340
6484
  "summary": "Provision an organization",
5341
6485
  "description": "Creates a new kelviq user + organization on behalf of the partner, issues API keys, and emails the user a link to set their password. Fails with `409` if `email` belongs to an existing kelviq user, or with `400` if `externalId` already exists for this partner.",
5342
6486
  "operationId": "provisionPartnerOrganization",
6487
+ "x-mint": {
6488
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6489
+ },
5343
6490
  "security": [{ "partnerKeyAuth": [] }],
5344
6491
  "requestBody": {
5345
6492
  "required": true,
@@ -5376,6 +6523,9 @@
5376
6523
  "summary": "List partner organizations",
5377
6524
  "description": "Returns organizations owned by the authenticated partner. Optionally filter by the partner-side `externalId`.",
5378
6525
  "operationId": "listPartnerOrganizations",
6526
+ "x-mint": {
6527
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6528
+ },
5379
6529
  "security": [{ "partnerKeyAuth": [] }],
5380
6530
  "parameters": [
5381
6531
  {
@@ -5429,6 +6579,9 @@
5429
6579
  "summary": "Get a partner organization by identifier",
5430
6580
  "description": "Retrieve a single organization owned by the authenticated partner, looked up by its kelviq UUID.",
5431
6581
  "operationId": "retrievePartnerOrganization",
6582
+ "x-mint": {
6583
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6584
+ },
5432
6585
  "security": [{ "partnerKeyAuth": [] }],
5433
6586
  "responses": {
5434
6587
  "200": {
@@ -5460,6 +6613,9 @@
5460
6613
  "summary": "Get a partner organization by external ID",
5461
6614
  "description": "Retrieve a single organization owned by the authenticated partner using the partner-side `externalId`.",
5462
6615
  "operationId": "retrievePartnerOrganizationByExternalId",
6616
+ "x-mint": {
6617
+ "content": "<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>"
6618
+ },
5463
6619
  "security": [{ "partnerKeyAuth": [] }],
5464
6620
  "responses": {
5465
6621
  "200": {