@kelviq/mcp-server 1.2.0 → 1.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 (111) hide show
  1. package/README.md +40 -3
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +1 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/ai/docs-for-agents.md +21 -0
  6. package/dist/docs/ai/overview.md +43 -0
  7. package/dist/docs/api-reference/authentication.md +9 -3
  8. package/dist/docs/api-reference/introduction.md +23 -2
  9. package/dist/docs/backend-integration/node-sdk.md +12 -6
  10. package/dist/docs/backend-integration/python-sdk.md +14 -8
  11. package/dist/docs/changelog.md +369 -3
  12. package/dist/docs/checkout/checkout-configuration.md +25 -75
  13. package/dist/docs/checkout/checkout-design.md +76 -0
  14. package/dist/docs/checkout/checkout-examples.md +212 -0
  15. package/dist/docs/checkout/checkout-metadata.md +1 -1
  16. package/dist/docs/checkout/custom-fields.md +60 -0
  17. package/dist/docs/checkout/embed-checkout.md +280 -0
  18. package/dist/docs/checkout/payment-methods/upi.md +69 -0
  19. package/dist/docs/checkout/payment-methods.md +119 -0
  20. package/dist/docs/checkout/static-checkout-url.md +3 -2
  21. package/dist/docs/cli/commands.md +57 -4
  22. package/dist/docs/cli/kelviq-config.md +1 -1
  23. package/dist/docs/cli/overview.md +1 -0
  24. package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
  25. package/dist/docs/customer-portal/overview.md +7 -7
  26. package/dist/docs/customer-portal/retention.md +109 -0
  27. package/dist/docs/customers-management/overview.md +105 -0
  28. package/dist/docs/frontend-integration/js-sdk.md +11 -11
  29. package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
  30. package/dist/docs/frontend-integration/react-sdk.md +8 -49
  31. package/dist/docs/frontend-integration/react-ui.md +8 -6
  32. package/dist/docs/getstarted/fees.md +27 -11
  33. package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
  34. package/dist/docs/getstarted/merchant-of-record.md +18 -24
  35. package/dist/docs/getstarted/overview.md +98 -0
  36. package/dist/docs/getstarted/review-process.md +59 -59
  37. package/dist/docs/guides/agent-toolkit.md +14 -9
  38. package/dist/docs/guides/mcp-server.md +24 -9
  39. package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
  40. package/dist/docs/guides/sandbox.md +6 -4
  41. package/dist/docs/guides/set-up-with-ai.md +43 -0
  42. package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
  43. package/dist/docs/guides/subscription-integration.md +1 -1
  44. package/dist/docs/guides/test-payments.md +640 -0
  45. package/dist/docs/guides/webhooks.md +182 -30
  46. package/dist/docs/integrations/woocommerce.md +88 -0
  47. package/dist/docs/integrations/zapier.md +22 -0
  48. package/dist/docs/legal/account-and-funds.md +59 -0
  49. package/dist/docs/legal/approved-prohibited-policy.md +32 -27
  50. package/dist/docs/legal/payment-flow-diagram.md +7 -7
  51. package/dist/docs/manifest.json +160 -41
  52. package/dist/docs/openapi.json +1359 -109
  53. package/dist/docs/payouts/overview.md +14 -12
  54. package/dist/docs/payouts/payout-account.md +1 -1
  55. package/dist/docs/payouts/transactions.md +3 -3
  56. package/dist/docs/product-catalog/create-a-feature.md +3 -3
  57. package/dist/docs/product-catalog/digital-downloads.md +5 -5
  58. package/dist/docs/product-catalog/discounts.md +2 -2
  59. package/dist/docs/product-catalog/entitlements.md +20 -27
  60. package/dist/docs/product-catalog/free-and-trials.md +5 -5
  61. package/dist/docs/product-catalog/license-keys.md +56 -29
  62. package/dist/docs/product-catalog/links.md +3 -3
  63. package/dist/docs/product-catalog/location-based-pricing.md +6 -10
  64. package/dist/docs/product-catalog/one-time-payments.md +3 -7
  65. package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
  66. package/dist/docs/product-catalog/plans.md +22 -19
  67. package/dist/docs/product-catalog/products.md +11 -3
  68. package/dist/docs/product-catalog/proration.md +69 -0
  69. package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
  70. package/dist/docs/product-catalog/subscriptions.md +52 -22
  71. package/dist/docs/product-catalog/tax-settings.md +8 -8
  72. package/dist/docs/product-catalog/usage-alerts.md +7 -7
  73. package/dist/docs/product-catalog/usage-based-billing.md +156 -29
  74. package/dist/docs/product-catalog/usage-limits.md +78 -0
  75. package/dist/docs/promotions/create-a-promotion.md +2 -2
  76. package/dist/docs/promotions/overview.md +1 -1
  77. package/dist/docs/quickstart/core-concepts.md +36 -30
  78. package/dist/docs/quickstart/dashboard-setup.md +26 -22
  79. package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
  80. package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
  81. package/dist/docs/sales/checkout-sessions.md +28 -39
  82. package/dist/docs/sales/orders.md +30 -54
  83. package/dist/docs/settings/customer-emails.md +52 -0
  84. package/dist/docs/settings/members.md +27 -0
  85. package/dist/docs/settings/profile.md +26 -0
  86. package/dist/docs/settings/zapier.md +22 -0
  87. package/dist/http/errors.d.ts +20 -1
  88. package/dist/http/errors.js +83 -31
  89. package/dist/http/errors.js.map +1 -1
  90. package/dist/schemas/kelviq.d.ts +54 -0
  91. package/dist/schemas/kelviq.js +64 -0
  92. package/dist/schemas/kelviq.js.map +1 -1
  93. package/dist/server.js +3 -2
  94. package/dist/server.js.map +1 -1
  95. package/dist/tools/_resolve.js +14 -10
  96. package/dist/tools/_resolve.js.map +1 -1
  97. package/dist/tools/features.js +9 -2
  98. package/dist/tools/features.js.map +1 -1
  99. package/dist/tools/imports.d.ts +68 -0
  100. package/dist/tools/imports.js +242 -0
  101. package/dist/tools/imports.js.map +1 -0
  102. package/dist/tools/index.d.ts +2 -1
  103. package/dist/tools/index.js +4 -1
  104. package/dist/tools/index.js.map +1 -1
  105. package/dist/tools/product-files.js +10 -3
  106. package/dist/tools/product-files.js.map +1 -1
  107. package/dist/tools/product-settings.js +10 -3
  108. package/dist/tools/product-settings.js.map +1 -1
  109. package/dist/tools/products.js +14 -4
  110. package/dist/tools/products.js.map +1 -1
  111. package/package.json +1 -1
@@ -99,6 +99,10 @@
99
99
  {
100
100
  "name": "Checkout Session Events",
101
101
  "description": "Timeline events for a specific checkout session."
102
+ },
103
+ {
104
+ "name": "Imports",
105
+ "description": "Bring an existing store from another platform into your Kelviq organization."
102
106
  }
103
107
  ],
104
108
  "components": {
@@ -108,6 +112,11 @@
108
112
  "scheme": "bearer",
109
113
  "description": "The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer __YOUR_API_KEY__'"
110
114
  },
115
+ "licenseBearerAuth": {
116
+ "type": "http",
117
+ "scheme": "bearer",
118
+ "description": "A Client API Key or Server API Key from the Kelviq application. Pass it as a Bearer token in the Authorization header. Use Client API Keys in customer-facing software and keep Server API Keys on trusted backends."
119
+ },
111
120
  "partnerKeyAuth": {
112
121
  "type": "apiKey",
113
122
  "in": "header",
@@ -438,6 +447,18 @@
438
447
  "description": "A comma-separated list of billing periods to display and allow on the checkout page. Values are case-insensitive and are normalized to uppercase.",
439
448
  "example": "MONTHLY,YEARLY"
440
449
  },
450
+ "customFields": {
451
+ "type": "array",
452
+ "items": {
453
+ "type": "string"
454
+ },
455
+ "nullable": true,
456
+ "description": "A list of custom field identifiers to collect from the customer during checkout. Active fields configured for your organization are displayed in their configured sort order, and the customer's responses are validated against each field's type and validation rules. Unknown or archived identifiers are ignored.",
457
+ "example": [
458
+ "company-name",
459
+ "purchase-order-number"
460
+ ]
461
+ },
441
462
  "currencyCode": {
442
463
  "type": "string",
443
464
  "nullable": true,
@@ -1819,6 +1840,341 @@
1819
1840
  }
1820
1841
  }
1821
1842
  },
1843
+ "RetentionOffersResponse": {
1844
+ "type": "object",
1845
+ "properties": {
1846
+ "enabled": {
1847
+ "type": "boolean",
1848
+ "description": "Whether retention offers are switched on for the organization. When `false`, every reason has `offer: null`."
1849
+ },
1850
+ "writtenFeedback": {
1851
+ "type": "object",
1852
+ "description": "Whether to ask the customer for a free-text comment, and the question to show. Pass the answer as `cancellationComment` when cancelling.",
1853
+ "properties": {
1854
+ "enabled": {
1855
+ "type": "boolean"
1856
+ },
1857
+ "question": {
1858
+ "type": "string",
1859
+ "nullable": true,
1860
+ "example": "What could we have done better?"
1861
+ }
1862
+ }
1863
+ },
1864
+ "reasons": {
1865
+ "type": "array",
1866
+ "description": "One entry per cancellation reason, in a fixed order.",
1867
+ "items": {
1868
+ "$ref": "#/components/schemas/RetentionReason"
1869
+ }
1870
+ }
1871
+ }
1872
+ },
1873
+ "RetentionReason": {
1874
+ "type": "object",
1875
+ "properties": {
1876
+ "reason": {
1877
+ "type": "string",
1878
+ "enum": [
1879
+ "TOO_EXPENSIVE",
1880
+ "MISSING_FEATURES",
1881
+ "SWITCHED_SERVICE",
1882
+ "UNUSED",
1883
+ "CUSTOMER_SERVICE",
1884
+ "LOW_QUALITY",
1885
+ "TOO_COMPLEX",
1886
+ "OTHER"
1887
+ ],
1888
+ "description": "The cancellation reason. Use the same value as `cancellationFeedback` when accepting an offer or cancelling.",
1889
+ "example": "TOO_EXPENSIVE"
1890
+ },
1891
+ "offer": {
1892
+ "nullable": true,
1893
+ "description": "The offer configured for this reason, or `null` when there is none.",
1894
+ "oneOf": [
1895
+ {
1896
+ "$ref": "#/components/schemas/RetentionDiscountOffer"
1897
+ },
1898
+ {
1899
+ "$ref": "#/components/schemas/RetentionPauseOffer"
1900
+ },
1901
+ {
1902
+ "$ref": "#/components/schemas/RetentionSupportOffer"
1903
+ }
1904
+ ],
1905
+ "discriminator": {
1906
+ "propertyName": "type",
1907
+ "mapping": {
1908
+ "DISCOUNT": "#/components/schemas/RetentionDiscountOffer",
1909
+ "PAUSE": "#/components/schemas/RetentionPauseOffer",
1910
+ "SUPPORT": "#/components/schemas/RetentionSupportOffer"
1911
+ }
1912
+ }
1913
+ }
1914
+ }
1915
+ },
1916
+ "RetentionDiscountOffer": {
1917
+ "type": "object",
1918
+ "required": [
1919
+ "type",
1920
+ "eligible"
1921
+ ],
1922
+ "properties": {
1923
+ "type": {
1924
+ "type": "string",
1925
+ "enum": [
1926
+ "DISCOUNT"
1927
+ ]
1928
+ },
1929
+ "percentageOff": {
1930
+ "type": "integer",
1931
+ "description": "Percentage taken off each invoice while the discount lasts.",
1932
+ "example": 20
1933
+ },
1934
+ "billingCycles": {
1935
+ "type": "integer",
1936
+ "description": "How many billing cycles the discount applies to.",
1937
+ "example": 3
1938
+ },
1939
+ "eligible": {
1940
+ "type": "boolean",
1941
+ "description": "Whether this subscription can take the offer right now."
1942
+ },
1943
+ "ineligibleReason": {
1944
+ "type": "string",
1945
+ "nullable": true,
1946
+ "enum": [
1947
+ "MANUAL_BILLING",
1948
+ "NOT_RECURRING",
1949
+ "FREE_SUBSCRIPTION",
1950
+ "SUBSCRIPTION_NOT_ACTIVE",
1951
+ "NOT_ACTIVE",
1952
+ "ALREADY_PAUSED",
1953
+ "SCHEDULED_TO_CANCEL",
1954
+ "ALREADY_TAKEN",
1955
+ "NO_USABLE_DURATION",
1956
+ "SHORTER_THAN_BILLING_PERIOD",
1957
+ "NOT_CONFIGURED"
1958
+ ],
1959
+ "description": "Why the offer cannot be taken, or `null` when `eligible` is `true`. `MANUAL_BILLING`, `NOT_RECURRING` and `FREE_SUBSCRIPTION` describe the subscription itself; `SUBSCRIPTION_NOT_ACTIVE`, `NOT_ACTIVE`, `ALREADY_PAUSED` and `SCHEDULED_TO_CANCEL` its current state; `ALREADY_TAKEN` means the organization's repeat policy blocks the offer; `NO_USABLE_DURATION` and `SHORTER_THAN_BILLING_PERIOD` mean every configured pause length is shorter than one billing period; `NOT_CONFIGURED` means the offer is missing its setup, such as a support URL."
1960
+ }
1961
+ }
1962
+ },
1963
+ "RetentionPauseOffer": {
1964
+ "type": "object",
1965
+ "required": [
1966
+ "type",
1967
+ "eligible"
1968
+ ],
1969
+ "properties": {
1970
+ "type": {
1971
+ "type": "string",
1972
+ "enum": [
1973
+ "PAUSE"
1974
+ ]
1975
+ },
1976
+ "durations": {
1977
+ "type": "array",
1978
+ "description": "Pause lengths the customer may choose. Only lengths that skip at least one renewal for this subscription are listed.",
1979
+ "items": {
1980
+ "type": "object",
1981
+ "properties": {
1982
+ "months": {
1983
+ "type": "integer",
1984
+ "example": 3
1985
+ },
1986
+ "billingResumesOn": {
1987
+ "type": "string",
1988
+ "format": "date",
1989
+ "description": "The date billing and access resume if this length is chosen. Aligned to the end of a billing period.",
1990
+ "example": "2027-02-01"
1991
+ }
1992
+ }
1993
+ }
1994
+ },
1995
+ "eligible": {
1996
+ "type": "boolean",
1997
+ "description": "Whether this subscription can take the offer right now."
1998
+ },
1999
+ "ineligibleReason": {
2000
+ "type": "string",
2001
+ "nullable": true,
2002
+ "enum": [
2003
+ "MANUAL_BILLING",
2004
+ "NOT_RECURRING",
2005
+ "FREE_SUBSCRIPTION",
2006
+ "SUBSCRIPTION_NOT_ACTIVE",
2007
+ "NOT_ACTIVE",
2008
+ "ALREADY_PAUSED",
2009
+ "SCHEDULED_TO_CANCEL",
2010
+ "ALREADY_TAKEN",
2011
+ "NO_USABLE_DURATION",
2012
+ "SHORTER_THAN_BILLING_PERIOD",
2013
+ "NOT_CONFIGURED"
2014
+ ],
2015
+ "description": "Why the offer cannot be taken, or `null` when `eligible` is `true`. `MANUAL_BILLING`, `NOT_RECURRING` and `FREE_SUBSCRIPTION` describe the subscription itself; `SUBSCRIPTION_NOT_ACTIVE`, `NOT_ACTIVE`, `ALREADY_PAUSED` and `SCHEDULED_TO_CANCEL` its current state; `ALREADY_TAKEN` means the organization's repeat policy blocks the offer; `NO_USABLE_DURATION` and `SHORTER_THAN_BILLING_PERIOD` mean every configured pause length is shorter than one billing period; `NOT_CONFIGURED` means the offer is missing its setup, such as a support URL."
2016
+ }
2017
+ }
2018
+ },
2019
+ "RetentionSupportOffer": {
2020
+ "type": "object",
2021
+ "required": [
2022
+ "type",
2023
+ "eligible"
2024
+ ],
2025
+ "properties": {
2026
+ "type": {
2027
+ "type": "string",
2028
+ "enum": [
2029
+ "SUPPORT"
2030
+ ]
2031
+ },
2032
+ "url": {
2033
+ "type": "string",
2034
+ "nullable": true,
2035
+ "description": "Where to send the customer, such as a booking page or a support form.",
2036
+ "example": "https://cal.com/acme/15min"
2037
+ },
2038
+ "eligible": {
2039
+ "type": "boolean",
2040
+ "description": "Whether this subscription can take the offer right now."
2041
+ },
2042
+ "ineligibleReason": {
2043
+ "type": "string",
2044
+ "nullable": true,
2045
+ "enum": [
2046
+ "MANUAL_BILLING",
2047
+ "NOT_RECURRING",
2048
+ "FREE_SUBSCRIPTION",
2049
+ "SUBSCRIPTION_NOT_ACTIVE",
2050
+ "NOT_ACTIVE",
2051
+ "ALREADY_PAUSED",
2052
+ "SCHEDULED_TO_CANCEL",
2053
+ "ALREADY_TAKEN",
2054
+ "NO_USABLE_DURATION",
2055
+ "SHORTER_THAN_BILLING_PERIOD",
2056
+ "NOT_CONFIGURED"
2057
+ ],
2058
+ "description": "Why the offer cannot be taken, or `null` when `eligible` is `true`. `MANUAL_BILLING`, `NOT_RECURRING` and `FREE_SUBSCRIPTION` describe the subscription itself; `SUBSCRIPTION_NOT_ACTIVE`, `NOT_ACTIVE`, `ALREADY_PAUSED` and `SCHEDULED_TO_CANCEL` its current state; `ALREADY_TAKEN` means the organization's repeat policy blocks the offer; `NO_USABLE_DURATION` and `SHORTER_THAN_BILLING_PERIOD` mean every configured pause length is shorter than one billing period; `NOT_CONFIGURED` means the offer is missing its setup, such as a support URL."
2059
+ }
2060
+ }
2061
+ },
2062
+ "AcceptRetentionOfferRequest": {
2063
+ "type": "object",
2064
+ "required": [
2065
+ "offerType",
2066
+ "cancellationFeedback"
2067
+ ],
2068
+ "properties": {
2069
+ "offerType": {
2070
+ "type": "string",
2071
+ "enum": [
2072
+ "DISCOUNT",
2073
+ "PAUSE",
2074
+ "SUPPORT"
2075
+ ],
2076
+ "description": "The offer to apply. Must be the offer configured for `cancellationFeedback`.",
2077
+ "example": "PAUSE"
2078
+ },
2079
+ "cancellationFeedback": {
2080
+ "type": "string",
2081
+ "enum": [
2082
+ "TOO_EXPENSIVE",
2083
+ "MISSING_FEATURES",
2084
+ "SWITCHED_SERVICE",
2085
+ "UNUSED",
2086
+ "CUSTOMER_SERVICE",
2087
+ "LOW_QUALITY",
2088
+ "TOO_COMPLEX",
2089
+ "OTHER"
2090
+ ],
2091
+ "description": "The cancellation reason the customer picked.",
2092
+ "example": "UNUSED"
2093
+ },
2094
+ "pauseMonths": {
2095
+ "type": "integer",
2096
+ "nullable": true,
2097
+ "minimum": 1,
2098
+ "description": "Required when `offerType` is `PAUSE`. Must be one of the `durations` returned by Get retention offers.",
2099
+ "example": 3
2100
+ }
2101
+ }
2102
+ },
2103
+ "AcceptRetentionOfferResponse": {
2104
+ "type": "object",
2105
+ "properties": {
2106
+ "message": {
2107
+ "type": "string",
2108
+ "example": "Subscription paused successfully"
2109
+ },
2110
+ "subscriptionId": {
2111
+ "type": "string",
2112
+ "format": "uuid"
2113
+ },
2114
+ "offerType": {
2115
+ "type": "string",
2116
+ "enum": [
2117
+ "DISCOUNT",
2118
+ "PAUSE",
2119
+ "SUPPORT"
2120
+ ]
2121
+ },
2122
+ "cancellationFeedback": {
2123
+ "type": "string",
2124
+ "enum": [
2125
+ "TOO_EXPENSIVE",
2126
+ "MISSING_FEATURES",
2127
+ "SWITCHED_SERVICE",
2128
+ "UNUSED",
2129
+ "CUSTOMER_SERVICE",
2130
+ "LOW_QUALITY",
2131
+ "TOO_COMPLEX",
2132
+ "OTHER"
2133
+ ]
2134
+ },
2135
+ "percentageOff": {
2136
+ "type": "integer",
2137
+ "description": "`DISCOUNT` only.",
2138
+ "example": 20
2139
+ },
2140
+ "billingCycles": {
2141
+ "type": "integer",
2142
+ "description": "`DISCOUNT` only.",
2143
+ "example": 3
2144
+ },
2145
+ "appliesUntil": {
2146
+ "type": "string",
2147
+ "format": "date-time",
2148
+ "nullable": true,
2149
+ "description": "`DISCOUNT` only. When the discount stops applying, or `null` when it applies to a single invoice."
2150
+ },
2151
+ "originalAmount": {
2152
+ "type": "string",
2153
+ "description": "`DISCOUNT` only. The amount billed per period before the discount.",
2154
+ "example": "50.00"
2155
+ },
2156
+ "discountedAmount": {
2157
+ "type": "string",
2158
+ "description": "`DISCOUNT` only. The amount billed per period while the discount lasts.",
2159
+ "example": "40.00"
2160
+ },
2161
+ "pauseMonths": {
2162
+ "type": "integer",
2163
+ "description": "`PAUSE` only.",
2164
+ "example": 3
2165
+ },
2166
+ "resumesAt": {
2167
+ "type": "string",
2168
+ "format": "date-time",
2169
+ "description": "`PAUSE` only. When billing and access resume."
2170
+ },
2171
+ "url": {
2172
+ "type": "string",
2173
+ "description": "`SUPPORT` only. The support URL to send the customer to.",
2174
+ "example": "https://cal.com/acme/15min"
2175
+ }
2176
+ }
2177
+ },
1822
2178
  "PublicOfferingResponse": {
1823
2179
  "type": "object",
1824
2180
  "properties": {
@@ -3538,10 +3894,13 @@
3538
3894
  "type": "string",
3539
3895
  "enum": [
3540
3896
  "ONE_TIME",
3541
- "DAILY",
3542
3897
  "MONTHLY",
3543
- "QUARTERLY",
3544
- "YEARLY"
3898
+ "YEARLY",
3899
+ "WEEKLY",
3900
+ "DAILY",
3901
+ "TWENTY_EIGHT_DAYS",
3902
+ "THREE_MONTHS",
3903
+ "SIX_MONTHS"
3545
3904
  ],
3546
3905
  "example": "MONTHLY"
3547
3906
  },
@@ -4739,11 +5098,28 @@
4739
5098
  "type": "string",
4740
5099
  "example": "$"
4741
5100
  },
5101
+ "startDate": {
5102
+ "type": "string",
5103
+ "format": "date",
5104
+ "description": "Date the subscription started.",
5105
+ "example": "2026-08-01"
5106
+ },
5107
+ "startDateTime": {
5108
+ "type": "string",
5109
+ "format": "date-time",
5110
+ "nullable": true,
5111
+ "description": "Exact instant the subscription started.",
5112
+ "example": "2026-08-01T10:14:22Z"
5113
+ },
4742
5114
  "nextInvoiceDate": {
4743
5115
  "type": "string",
4744
5116
  "format": "date-time",
4745
5117
  "nullable": true,
4746
5118
  "example": "2026-08-28T10:46:34Z"
5119
+ },
5120
+ "trialDaysRemaining": {
5121
+ "type": "integer",
5122
+ "example": 0
4747
5123
  }
4748
5124
  }
4749
5125
  },
@@ -4990,23 +5366,63 @@
4990
5366
  "type": "object",
4991
5367
  "description": "The raw event envelope sent to the destination. For `invoice.created`, `invoice.paid`, and `invoice.payment_failed`, `data.object.payment_link` contains a customer payment URL for the invoice.",
4992
5368
  "additionalProperties": true
4993
- }
4994
- },
4995
- "required": [
4996
- "id",
4997
- "eventId",
4998
- "endpoint",
4999
- "eventType",
5000
- "statusCode",
5001
- "isSuccess",
5002
- "retryCount",
5003
- "lastAttempt",
5004
- "createdOn",
5005
- "payload"
5006
- ]
5007
- },
5008
- "WebhookEventLogListResponse": {
5009
- "type": "object",
5369
+ },
5370
+ "endpointName": {
5371
+ "type": "string",
5372
+ "nullable": true,
5373
+ "example": "Slack alerts"
5374
+ },
5375
+ "attemptNumber": {
5376
+ "type": "integer",
5377
+ "description": "1 for the first delivery attempt; resends and automatic retries count up from there.",
5378
+ "example": 3
5379
+ },
5380
+ "maxAttempts": {
5381
+ "type": "integer",
5382
+ "description": "Attempts Kelviq makes automatically: the first delivery plus 3 retries.",
5383
+ "example": 4
5384
+ },
5385
+ "willRetry": {
5386
+ "type": "boolean",
5387
+ "description": "True only on the newest attempt of an event whose next automatic retry is still scheduled."
5388
+ },
5389
+ "nextRetryAt": {
5390
+ "type": "string",
5391
+ "format": "date-time",
5392
+ "nullable": true,
5393
+ "description": "When the next automatic attempt is due; set only when `willRetry` is true."
5394
+ },
5395
+ "durationMs": {
5396
+ "type": "integer",
5397
+ "nullable": true,
5398
+ "description": "Round-trip time of this attempt in milliseconds; `null` when no response arrived.",
5399
+ "example": 1240
5400
+ },
5401
+ "responseBody": {
5402
+ "type": "string",
5403
+ "nullable": true,
5404
+ "description": "First 1000 characters of the destination's response, or the connection error."
5405
+ },
5406
+ "isTest": {
5407
+ "type": "boolean",
5408
+ "description": "True for deliveries made with **Send test event**; their payload also carries `\"test\": true`."
5409
+ }
5410
+ },
5411
+ "required": [
5412
+ "id",
5413
+ "eventId",
5414
+ "endpoint",
5415
+ "eventType",
5416
+ "statusCode",
5417
+ "isSuccess",
5418
+ "retryCount",
5419
+ "lastAttempt",
5420
+ "createdOn",
5421
+ "payload"
5422
+ ]
5423
+ },
5424
+ "WebhookEventLogListResponse": {
5425
+ "type": "object",
5010
5426
  "properties": {
5011
5427
  "count": {
5012
5428
  "type": "integer",
@@ -6043,6 +6459,17 @@
6043
6459
  "format": "uuid",
6044
6460
  "example": "2f6b9e2a-7c1a-4a3e-8b6e-8e6f9a2c1d4a"
6045
6461
  },
6462
+ "name": {
6463
+ "type": "string",
6464
+ "maxLength": 100,
6465
+ "description": "Display name. Optional on create: when omitted or blank it defaults to the URL's host, for example `api.acmecorp.com`.",
6466
+ "example": "Production billing sync"
6467
+ },
6468
+ "description": {
6469
+ "type": "string",
6470
+ "description": "Free-text note shown in the dashboard.",
6471
+ "example": "Sends billing events to our production API."
6472
+ },
6046
6473
  "url": {
6047
6474
  "type": "string",
6048
6475
  "format": "uri",
@@ -6084,18 +6511,110 @@
6084
6511
  },
6085
6512
  "secret": {
6086
6513
  "type": "string",
6087
- "description": "Signing secret used to verify the `Kelviq-Signature` header on deliveries to this endpoint.",
6514
+ "readOnly": true,
6515
+ "description": "Signing secret used to verify the `webhook-signature` header on deliveries to this endpoint. `secretPreview` is a masked form of the same value for display."
6516
+ },
6517
+ "secretPreview": {
6518
+ "type": "string",
6519
+ "readOnly": true,
6520
+ "description": "The secret's prefix and last four characters, for display.",
6521
+ "example": "kq_whsec_\u2022\u2022\u2022\u2022pW6z"
6522
+ },
6523
+ "verifiedAt": {
6524
+ "type": "string",
6525
+ "format": "date-time",
6526
+ "nullable": true,
6527
+ "readOnly": true,
6528
+ "description": "When **Verify endpoint** last got an answer from the URL (any HTTP status). Cleared when the URL is changed."
6529
+ },
6530
+ "createdOn": {
6531
+ "type": "string",
6532
+ "format": "date-time",
6088
6533
  "readOnly": true
6534
+ },
6535
+ "createdByName": {
6536
+ "type": "string",
6537
+ "nullable": true,
6538
+ "readOnly": true,
6539
+ "example": "Priya Shah"
6540
+ },
6541
+ "status": {
6542
+ "type": "string",
6543
+ "enum": [
6544
+ "active",
6545
+ "failing",
6546
+ "disabled"
6547
+ ],
6548
+ "readOnly": true,
6549
+ "description": "`disabled` when `enabled` is false; otherwise `failing` when the most recent delivery to this endpoint did not succeed (including one still being retried), else `active`. Test sends are not considered."
6550
+ },
6551
+ "deliveryCount": {
6552
+ "type": "integer",
6553
+ "readOnly": true,
6554
+ "description": "Events delivered (or attempted) to this endpoint in the period selected with `start_date`/`end_date` on the list call, defaulting to the last 7 days. Test events are not counted.",
6555
+ "example": 10763
6556
+ },
6557
+ "recentDeliveries": {
6558
+ "type": "array",
6559
+ "readOnly": true,
6560
+ "items": {
6561
+ "type": "boolean"
6562
+ },
6563
+ "description": "Outcome of the last 8 deliveries, oldest first (`true` = delivered). Test sends are not included.",
6564
+ "example": [
6565
+ true,
6566
+ true,
6567
+ true,
6568
+ false
6569
+ ]
6570
+ },
6571
+ "lastDelivery": {
6572
+ "type": "object",
6573
+ "nullable": true,
6574
+ "readOnly": true,
6575
+ "description": "The most recent delivery to this endpoint, or `null` before the first one.",
6576
+ "properties": {
6577
+ "eventId": {
6578
+ "type": "string",
6579
+ "format": "uuid"
6580
+ },
6581
+ "at": {
6582
+ "type": "string",
6583
+ "format": "date-time"
6584
+ },
6585
+ "isSuccess": {
6586
+ "type": "boolean"
6587
+ },
6588
+ "statusCode": {
6589
+ "type": "integer",
6590
+ "nullable": true
6591
+ },
6592
+ "retrying": {
6593
+ "type": "boolean",
6594
+ "description": "True while an automatic retry is still scheduled."
6595
+ }
6596
+ }
6089
6597
  }
6090
6598
  }
6091
6599
  },
6092
6600
  "WebhookEndpointCreateRequest": {
6093
6601
  "type": "object",
6094
6602
  "properties": {
6603
+ "name": {
6604
+ "type": "string",
6605
+ "maxLength": 100,
6606
+ "description": "Display name. Optional on create: when omitted or blank it defaults to the URL's host, for example `api.acmecorp.com`.",
6607
+ "example": "Production billing sync"
6608
+ },
6609
+ "description": {
6610
+ "type": "string",
6611
+ "description": "Free-text note shown in the dashboard.",
6612
+ "example": "Sends billing events to our production API."
6613
+ },
6095
6614
  "url": {
6096
6615
  "type": "string",
6097
6616
  "format": "uri",
6098
- "description": "Must be a public HTTPS/HTTP URL \u2014 URLs resolving to a private, loopback, link-local, or otherwise internal address are rejected."
6617
+ "description": "Must be a public HTTPS/HTTP URL \u2014 a malformed URL, or one resolving to a private, loopback, link-local, or otherwise internal address, is rejected with 400. A host that does not resolve yet is accepted."
6099
6618
  },
6100
6619
  "events": {
6101
6620
  "type": "array",
@@ -6123,7 +6642,9 @@
6123
6642
  "payment_method.updated",
6124
6643
  "payment_method.deleted"
6125
6644
  ]
6126
- }
6645
+ },
6646
+ "minItems": 1,
6647
+ "description": "Event types to subscribe to. At least one is required."
6127
6648
  },
6128
6649
  "enabled": {
6129
6650
  "type": "boolean",
@@ -6138,6 +6659,17 @@
6138
6659
  "WebhookEndpointUpdateRequest": {
6139
6660
  "type": "object",
6140
6661
  "properties": {
6662
+ "name": {
6663
+ "type": "string",
6664
+ "maxLength": 100,
6665
+ "description": "Display name. Optional on create: when omitted or blank it defaults to the URL's host, for example `api.acmecorp.com`.",
6666
+ "example": "Production billing sync"
6667
+ },
6668
+ "description": {
6669
+ "type": "string",
6670
+ "description": "Free-text note shown in the dashboard.",
6671
+ "example": "Sends billing events to our production API."
6672
+ },
6141
6673
  "url": {
6142
6674
  "type": "string",
6143
6675
  "format": "uri"
@@ -6168,7 +6700,9 @@
6168
6700
  "payment_method.updated",
6169
6701
  "payment_method.deleted"
6170
6702
  ]
6171
- }
6703
+ },
6704
+ "minItems": 1,
6705
+ "description": "Event types to subscribe to. At least one is required."
6172
6706
  },
6173
6707
  "enabled": {
6174
6708
  "type": "boolean"
@@ -6198,6 +6732,157 @@
6198
6732
  }
6199
6733
  }
6200
6734
  }
6735
+ },
6736
+ "LemonSqueezyImportRequest": {
6737
+ "type": "object",
6738
+ "required": [
6739
+ "apiKey",
6740
+ "storeId"
6741
+ ],
6742
+ "properties": {
6743
+ "apiKey": {
6744
+ "type": "string",
6745
+ "description": "Your Lemon Squeezy API key. Used for this import only. It is never returned in a response or included in the report email."
6746
+ },
6747
+ "storeId": {
6748
+ "type": "string",
6749
+ "pattern": "^[0-9]+$",
6750
+ "description": "The Lemon Squeezy store to import, as a string of digits. A key can reach several stores; one store is imported per request.",
6751
+ "example": "12345"
6752
+ },
6753
+ "reportEmail": {
6754
+ "type": "string",
6755
+ "format": "email",
6756
+ "description": "Where the summary email is sent. Defaults to the organization owner's email."
6757
+ },
6758
+ "dryRun": {
6759
+ "type": "boolean",
6760
+ "default": false,
6761
+ "description": "Run the whole import and save nothing. The report email shows what a real run would do."
6762
+ },
6763
+ "orderType": {
6764
+ "type": "string",
6765
+ "enum": [
6766
+ "all",
6767
+ "one_time",
6768
+ "subscription"
6769
+ ],
6770
+ "default": "all",
6771
+ "description": "Which sales to import. `all` imports every order and every subscription renewal. `one_time` imports only orders that did not start a subscription. `subscription` imports only orders that started a subscription, plus their renewals. License keys follow their orders. Products, plans, customers, files and discounts are imported whichever value is sent."
6772
+ },
6773
+ "only": {
6774
+ "type": "array",
6775
+ "items": {
6776
+ "type": "string",
6777
+ "enum": [
6778
+ "store",
6779
+ "products",
6780
+ "customers",
6781
+ "files",
6782
+ "orders",
6783
+ "renewals",
6784
+ "discounts",
6785
+ "licenses"
6786
+ ]
6787
+ },
6788
+ "description": "Run only these steps. Defaults to every step."
6789
+ },
6790
+ "skip": {
6791
+ "type": "array",
6792
+ "items": {
6793
+ "type": "string",
6794
+ "enum": [
6795
+ "store",
6796
+ "products",
6797
+ "customers",
6798
+ "files",
6799
+ "orders",
6800
+ "renewals",
6801
+ "discounts",
6802
+ "licenses"
6803
+ ]
6804
+ },
6805
+ "description": "Leave these steps out."
6806
+ },
6807
+ "publishPlan": {
6808
+ "type": "boolean",
6809
+ "default": true,
6810
+ "description": "Publish each imported plan so it can be sold straight away, including a plan an earlier import left as a draft. When `false`, plans arrive as drafts to review and publish."
6811
+ },
6812
+ "publishDiscount": {
6813
+ "type": "boolean",
6814
+ "default": true,
6815
+ "description": "Make each imported discount code usable at checkout, including a code an earlier import left switched off. A code limited to plans that are not published stays off. When `false`, codes arrive switched off."
6816
+ },
6817
+ "overwriteProfile": {
6818
+ "type": "boolean",
6819
+ "default": false,
6820
+ "description": "Overwrite the organization name and business profile fields that are already filled in. When `false`, only blank fields are filled."
6821
+ },
6822
+ "skipAnalytics": {
6823
+ "type": "boolean",
6824
+ "default": false,
6825
+ "description": "Do not add the imported sales to revenue analytics."
6826
+ }
6827
+ }
6828
+ },
6829
+ "LemonSqueezyImportQueued": {
6830
+ "type": "object",
6831
+ "properties": {
6832
+ "status": {
6833
+ "type": "string",
6834
+ "enum": [
6835
+ "queued"
6836
+ ],
6837
+ "description": "Always `queued`. Nothing has been imported yet."
6838
+ },
6839
+ "taskId": {
6840
+ "type": "string",
6841
+ "format": "uuid",
6842
+ "description": "A reference for support. It cannot be used to query progress."
6843
+ },
6844
+ "storeId": {
6845
+ "type": "string"
6846
+ },
6847
+ "storeName": {
6848
+ "type": "string",
6849
+ "nullable": true,
6850
+ "description": "The store's name from Lemon Squeezy. `null` if Lemon Squeezy could not be reached during the check; the import is still queued."
6851
+ },
6852
+ "steps": {
6853
+ "type": "array",
6854
+ "items": {
6855
+ "type": "string",
6856
+ "enum": [
6857
+ "store",
6858
+ "products",
6859
+ "customers",
6860
+ "files",
6861
+ "orders",
6862
+ "renewals",
6863
+ "discounts",
6864
+ "licenses"
6865
+ ]
6866
+ },
6867
+ "description": "The steps that will run, after `only` and `skip` are applied."
6868
+ },
6869
+ "orderType": {
6870
+ "type": "string",
6871
+ "enum": [
6872
+ "all",
6873
+ "one_time",
6874
+ "subscription"
6875
+ ]
6876
+ },
6877
+ "dryRun": {
6878
+ "type": "boolean"
6879
+ },
6880
+ "reportEmail": {
6881
+ "type": "string",
6882
+ "format": "email",
6883
+ "description": "The address the summary will be sent to."
6884
+ }
6885
+ }
6201
6886
  }
6202
6887
  }
6203
6888
  },
@@ -6488,21 +7173,21 @@
6488
7173
  "name": "start_date",
6489
7174
  "in": "query",
6490
7175
  "required": false,
6491
- "description": "Include sessions created on or after this date.",
7176
+ "description": "Include sessions created on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with a UTC offset (for example `2026-07-01T00:00:00+05:30`) for an exact instant. URL-encode `+` as `%2B`.",
6492
7177
  "schema": {
6493
- "type": "string",
6494
- "format": "date"
6495
- }
7178
+ "type": "string"
7179
+ },
7180
+ "example": "2026-07-01T00:00:00+05:30"
6496
7181
  },
6497
7182
  {
6498
7183
  "name": "end_date",
6499
7184
  "in": "query",
6500
7185
  "required": false,
6501
- "description": "Include sessions created on or before this date.",
7186
+ "description": "Include sessions created on or before this date. A date (`YYYY-MM-DD`) includes the whole UTC day. A datetime is an exclusive upper bound, so pass the next local midnight (for example `2026-07-02T00:00:00+05:30`) to get exactly one local day. URL-encode `+` as `%2B`.",
6502
7187
  "schema": {
6503
- "type": "string",
6504
- "format": "date"
6505
- }
7188
+ "type": "string"
7189
+ },
7190
+ "example": "2026-07-02T00:00:00+05:30"
6506
7191
  },
6507
7192
  {
6508
7193
  "name": "page_size",
@@ -6755,13 +7440,18 @@
6755
7440
  "post": {
6756
7441
  "operationId": "licenseActivate",
6757
7442
  "x-mint": {
6758
- "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>"
7443
+ "content": "<Info>This endpoint accepts either a **Client API Key** or a **Server API Key** as a Bearer token. Use a Client API Key in browser or distributed client software, and keep Server API Keys on trusted backends. Select the matching Sandbox or Production host and key.</Info>"
6759
7444
  },
6760
7445
  "tags": [
6761
7446
  "License"
6762
7447
  ],
6763
7448
  "summary": "Activate License",
6764
- "description": "Activates a license key for a specific instance.",
7449
+ "description": "Activates a license key for a specific instance. Accepts either a Client API Key or a Server API Key as a Bearer token.",
7450
+ "security": [
7451
+ {
7452
+ "licenseBearerAuth": []
7453
+ }
7454
+ ],
6765
7455
  "requestBody": {
6766
7456
  "required": true,
6767
7457
  "content": {
@@ -6894,12 +7584,18 @@
6894
7584
  "post": {
6895
7585
  "operationId": "licenseDeactivate",
6896
7586
  "x-mint": {
6897
- "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>"
7587
+ "content": "<Info>This endpoint accepts either a **Client API Key** or a **Server API Key** as a Bearer token. Use a Client API Key in browser or distributed client software, and keep Server API Keys on trusted backends. Select the matching Sandbox or Production host and key.</Info>"
6898
7588
  },
6899
7589
  "tags": [
6900
7590
  "License"
6901
7591
  ],
6902
7592
  "summary": "Deactivate License",
7593
+ "description": "Deactivates a specific license instance. Accepts either a Client API Key or a Server API Key as a Bearer token.",
7594
+ "security": [
7595
+ {
7596
+ "licenseBearerAuth": []
7597
+ }
7598
+ ],
6903
7599
  "requestBody": {
6904
7600
  "required": true,
6905
7601
  "content": {
@@ -6961,12 +7657,18 @@
6961
7657
  "post": {
6962
7658
  "operationId": "licenseValidate",
6963
7659
  "x-mint": {
6964
- "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>"
7660
+ "content": "<Info>This endpoint accepts either a **Client API Key** or a **Server API Key** as a Bearer token. Use a Client API Key in browser or distributed client software, and keep Server API Keys on trusted backends. Select the matching Sandbox or Production host and key.</Info>"
6965
7661
  },
6966
7662
  "tags": [
6967
7663
  "License"
6968
7664
  ],
6969
7665
  "summary": "Validate License",
7666
+ "description": "Validates a license key and, when provided, a specific instance. Accepts either a Client API Key or a Server API Key as a Bearer token.",
7667
+ "security": [
7668
+ {
7669
+ "licenseBearerAuth": []
7670
+ }
7671
+ ],
6970
7672
  "requestBody": {
6971
7673
  "required": true,
6972
7674
  "content": {
@@ -7166,21 +7868,21 @@
7166
7868
  "name": "start_date",
7167
7869
  "in": "query",
7168
7870
  "required": false,
7169
- "description": "Include transactions created on or after this date.",
7871
+ "description": "Include transactions created on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with a UTC offset (for example `2026-07-01T00:00:00+05:30`) for an exact instant. URL-encode `+` as `%2B`.",
7170
7872
  "schema": {
7171
- "type": "string",
7172
- "format": "date"
7173
- }
7873
+ "type": "string"
7874
+ },
7875
+ "example": "2026-07-01T00:00:00+05:30"
7174
7876
  },
7175
7877
  {
7176
7878
  "name": "end_date",
7177
7879
  "in": "query",
7178
7880
  "required": false,
7179
- "description": "Include transactions created on or before this date.",
7881
+ "description": "Include transactions created on or before this date. A date (`YYYY-MM-DD`) includes the whole UTC day. A datetime is an exclusive upper bound, so pass the next local midnight (for example `2026-07-02T00:00:00+05:30`) to get exactly one local day. URL-encode `+` as `%2B`.",
7180
7882
  "schema": {
7181
- "type": "string",
7182
- "format": "date"
7183
- }
7883
+ "type": "string"
7884
+ },
7885
+ "example": "2026-07-02T00:00:00+05:30"
7184
7886
  },
7185
7887
  {
7186
7888
  "name": "page_size",
@@ -7286,21 +7988,21 @@
7286
7988
  "name": "start_date",
7287
7989
  "in": "query",
7288
7990
  "required": false,
7289
- "description": "Include orders paid on or after this date.",
7991
+ "description": "Include orders paid on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with a UTC offset (for example `2026-07-01T00:00:00+05:30`) for an exact instant. URL-encode `+` as `%2B`.",
7290
7992
  "schema": {
7291
- "type": "string",
7292
- "format": "date"
7293
- }
7993
+ "type": "string"
7994
+ },
7995
+ "example": "2026-07-01T00:00:00+05:30"
7294
7996
  },
7295
7997
  {
7296
7998
  "name": "end_date",
7297
7999
  "in": "query",
7298
8000
  "required": false,
7299
- "description": "Include orders paid on or before this date.",
8001
+ "description": "Include orders paid on or before this date. A date (`YYYY-MM-DD`) includes the whole UTC day. A datetime is an exclusive upper bound, so pass the next local midnight (for example `2026-07-02T00:00:00+05:30`) to get exactly one local day. URL-encode `+` as `%2B`.",
7300
8002
  "schema": {
7301
- "type": "string",
7302
- "format": "date"
7303
- }
8003
+ "type": "string"
8004
+ },
8005
+ "example": "2026-07-02T00:00:00+05:30"
7304
8006
  },
7305
8007
  {
7306
8008
  "name": "page_size",
@@ -7558,7 +8260,10 @@
7558
8260
  "currency": "usd",
7559
8261
  "interval": "month",
7560
8262
  "currencySymbol": "$",
7561
- "nextInvoiceDate": "2026-09-01T10:14:22Z"
8263
+ "startDate": "2026-08-01",
8264
+ "startDateTime": "2026-08-01T10:14:22Z",
8265
+ "nextInvoiceDate": "2026-09-01T10:14:22Z",
8266
+ "trialDaysRemaining": 0
7562
8267
  },
7563
8268
  "paymentId": null,
7564
8269
  "paymentLink": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
@@ -7673,7 +8378,10 @@
7673
8378
  "currency": "usd",
7674
8379
  "interval": "month",
7675
8380
  "currencySymbol": "$",
7676
- "nextInvoiceDate": "2026-09-01T10:14:22Z"
8381
+ "startDate": "2026-08-01",
8382
+ "startDateTime": "2026-08-01T10:14:22Z",
8383
+ "nextInvoiceDate": "2026-09-01T10:14:22Z",
8384
+ "trialDaysRemaining": 0
7677
8385
  },
7678
8386
  "paymentId": null,
7679
8387
  "paymentLink": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
@@ -7727,25 +8435,86 @@
7727
8435
  },
7728
8436
  "parameters": [
7729
8437
  {
7730
- "name": "start_date",
8438
+ "name": "status",
7731
8439
  "in": "query",
7732
8440
  "required": false,
7733
- "description": "Include delivery attempts made on or after this date. Clamped to at most 30 days back regardless of the value passed.",
8441
+ "description": "`delivered` (2xx) or `failed` attempts only.",
7734
8442
  "schema": {
7735
8443
  "type": "string",
7736
- "format": "date"
8444
+ "enum": [
8445
+ "delivered",
8446
+ "failed"
8447
+ ]
7737
8448
  }
7738
8449
  },
7739
8450
  {
7740
- "name": "end_date",
8451
+ "name": "endpoint",
7741
8452
  "in": "query",
7742
8453
  "required": false,
7743
- "description": "Include delivery attempts made on or before this date.",
8454
+ "description": "Attempts to one endpoint.",
7744
8455
  "schema": {
7745
8456
  "type": "string",
7746
- "format": "date"
8457
+ "format": "uuid"
7747
8458
  }
7748
8459
  },
8460
+ {
8461
+ "name": "event_type",
8462
+ "in": "query",
8463
+ "required": false,
8464
+ "description": "Attempts for one event type.",
8465
+ "schema": {
8466
+ "type": "string"
8467
+ },
8468
+ "example": "invoice.payment_failed"
8469
+ },
8470
+ {
8471
+ "name": "search",
8472
+ "in": "query",
8473
+ "required": false,
8474
+ "description": "An event ID, or its leading characters, to find every attempt of that event.",
8475
+ "schema": {
8476
+ "type": "string"
8477
+ },
8478
+ "example": "5b274952"
8479
+ },
8480
+ {
8481
+ "name": "test",
8482
+ "in": "query",
8483
+ "required": false,
8484
+ "description": "`true` for test-event deliveries only, `false` to leave them out.",
8485
+ "schema": {
8486
+ "type": "boolean"
8487
+ }
8488
+ },
8489
+ {
8490
+ "name": "latest_only",
8491
+ "in": "query",
8492
+ "required": false,
8493
+ "description": "`true` returns one row per event: its newest attempt.",
8494
+ "schema": {
8495
+ "type": "boolean"
8496
+ }
8497
+ },
8498
+ {
8499
+ "name": "start_date",
8500
+ "in": "query",
8501
+ "required": false,
8502
+ "description": "Include delivery attempts made on or after this date. Clamped to at most 30 days back regardless of the value passed. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with a UTC offset (for example `2026-07-01T00:00:00+05:30`) for an exact instant. URL-encode `+` as `%2B`.",
8503
+ "schema": {
8504
+ "type": "string"
8505
+ },
8506
+ "example": "2026-07-01T00:00:00+05:30"
8507
+ },
8508
+ {
8509
+ "name": "end_date",
8510
+ "in": "query",
8511
+ "required": false,
8512
+ "description": "Include delivery attempts made on or before this date. A date (`YYYY-MM-DD`) includes the whole UTC day. A datetime is an exclusive upper bound, so pass the next local midnight (for example `2026-07-02T00:00:00+05:30`) to get exactly one local day. URL-encode `+` as `%2B`.",
8513
+ "schema": {
8514
+ "type": "string"
8515
+ },
8516
+ "example": "2026-07-02T00:00:00+05:30"
8517
+ },
7749
8518
  {
7750
8519
  "name": "page_size",
7751
8520
  "in": "query",
@@ -7826,21 +8595,21 @@
7826
8595
  "name": "start_date",
7827
8596
  "in": "query",
7828
8597
  "required": false,
7829
- "description": "Include refunds created on or after this date.",
8598
+ "description": "Include refunds created on or after this date. Accepts a date (`YYYY-MM-DD`, treated as a UTC calendar day) or an ISO 8601 datetime with a UTC offset (for example `2026-07-01T00:00:00+05:30`) for an exact instant. URL-encode `+` as `%2B`.",
7830
8599
  "schema": {
7831
- "type": "string",
7832
- "format": "date"
7833
- }
8600
+ "type": "string"
8601
+ },
8602
+ "example": "2026-07-01T00:00:00+05:30"
7834
8603
  },
7835
8604
  {
7836
8605
  "name": "end_date",
7837
8606
  "in": "query",
7838
8607
  "required": false,
7839
- "description": "Include refunds created on or before this date.",
8608
+ "description": "Include refunds created on or before this date. A date (`YYYY-MM-DD`) includes the whole UTC day. A datetime is an exclusive upper bound, so pass the next local midnight (for example `2026-07-02T00:00:00+05:30`) to get exactly one local day. URL-encode `+` as `%2B`.",
7840
8609
  "schema": {
7841
- "type": "string",
7842
- "format": "date"
7843
- }
8610
+ "type": "string"
8611
+ },
8612
+ "example": "2026-07-02T00:00:00+05:30"
7844
8613
  },
7845
8614
  {
7846
8615
  "name": "page_size",
@@ -8561,51 +9330,229 @@
8561
9330
  }
8562
9331
  }
8563
9332
  }
8564
- },
9333
+ },
9334
+ "responses": {
9335
+ "200": {
9336
+ "description": "The proposed update was priced successfully; no changes were applied.",
9337
+ "content": {
9338
+ "application/json": {
9339
+ "schema": {
9340
+ "$ref": "#/components/schemas/SubscriptionUpdatePreviewResponse"
9341
+ },
9342
+ "example": {
9343
+ "currency": "USD",
9344
+ "recurringAmount": 50,
9345
+ "recurringAmountUnits": 5000,
9346
+ "amountChargedImmediately": 39.5,
9347
+ "amountChargedImmediatelyUnits": 3950,
9348
+ "nextInvoice": {
9349
+ "amountDue": 39.5,
9350
+ "amountDueUnits": 3950,
9351
+ "nextPaymentAttempt": "2026-09-01T00:00:00Z",
9352
+ "lineItems": [
9353
+ {
9354
+ "description": "Unused time on Pro after 12 Aug 2026",
9355
+ "amount": -10.5,
9356
+ "amountUnits": -1050
9357
+ },
9358
+ {
9359
+ "description": "Remaining time on Enterprise after 12 Aug 2026",
9360
+ "amount": 50,
9361
+ "amountUnits": 5000
9362
+ }
9363
+ ]
9364
+ }
9365
+ }
9366
+ }
9367
+ }
9368
+ },
9369
+ "400": {
9370
+ "description": "Bad Request - Invalid subscription update, pricing configuration, or payment-provider preview error.",
9371
+ "content": {
9372
+ "application/json": {
9373
+ "schema": {
9374
+ "$ref": "#/components/schemas/DetailErrorResponse"
9375
+ },
9376
+ "example": {
9377
+ "detail": "Subscription does not exists"
9378
+ }
9379
+ }
9380
+ }
9381
+ }
9382
+ }
9383
+ }
9384
+ },
9385
+ "/subscriptions/{subscriptionId}/cancel/": {
9386
+ "post": {
9387
+ "tags": [
9388
+ "Subscriptions"
9389
+ ],
9390
+ "summary": "Cancel a subscription",
9391
+ "description": "Cancels an active subscription for a customer.",
9392
+ "operationId": "cancelSubscription",
9393
+ "x-mint": {
9394
+ "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>"
9395
+ },
9396
+ "parameters": [
9397
+ {
9398
+ "name": "subscriptionId",
9399
+ "in": "path",
9400
+ "required": true,
9401
+ "description": "The unique identifier of the subscription to be cancelled. Example UUID from docs: 78058918-9746-4280-9b9b-1bd5115eec6e",
9402
+ "example": "78058918-9746-4280-9b9b-1bd5115eec6e",
9403
+ "schema": {
9404
+ "type": "string",
9405
+ "format": "uuid"
9406
+ }
9407
+ }
9408
+ ],
9409
+ "requestBody": {
9410
+ "required": true,
9411
+ "content": {
9412
+ "application/json": {
9413
+ "schema": {
9414
+ "$ref": "#/components/schemas/CancelSubscriptionRequest"
9415
+ },
9416
+ "example": {
9417
+ "cancellationType": "CURRENT_PERIOD_ENDS",
9418
+ "cancellationFeedback": "TOO_EXPENSIVE",
9419
+ "cancellationComment": "The plan no longer fits our budget."
9420
+ }
9421
+ }
9422
+ }
9423
+ },
9424
+ "responses": {
9425
+ "200": {
9426
+ "description": "Subscription cancellation processed successfully.",
9427
+ "content": {
9428
+ "application/json": {
9429
+ "schema": {
9430
+ "$ref": "#/components/schemas/CancelSubscriptionResponse"
9431
+ },
9432
+ "example": {
9433
+ "message": "Subscription cancellation processed successfully."
9434
+ }
9435
+ }
9436
+ }
9437
+ }
9438
+ }
9439
+ }
9440
+ },
9441
+ "/subscriptions/{subscriptionId}/retention/": {
9442
+ "get": {
9443
+ "tags": [
9444
+ "Subscriptions"
9445
+ ],
9446
+ "summary": "Get retention offers",
9447
+ "description": "Returns what this subscription can be offered for each cancellation reason, so you can build the cancellation flow in your own app.\n\nEvery cancellation reason is listed with the offer configured for it in the Kelviq dashboard retention settings: a discount, a pause, a link to support, or nothing. Each offer carries an eligibility verdict for this particular subscription. An ineligible offer is still returned with `ineligibleReason` set, so you can show it greyed out with an explanation rather than hide it.\n\nWhen retention is switched off, `enabled` is `false` and every reason comes back with `offer: null`. The reason list is still returned so the same reason picker can be rendered either way.\n\nTo apply the offer the customer chooses, call [Accept a retention offer](/api-reference/subscriptions/accept-a-retention-offer). To record the cancellation instead, call [Cancel a subscription](/api-reference/subscriptions/cancel-a-subscription) with the same `cancellationFeedback`.",
9448
+ "operationId": "getRetentionOffers",
9449
+ "x-mint": {
9450
+ "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>"
9451
+ },
9452
+ "parameters": [
9453
+ {
9454
+ "name": "subscriptionId",
9455
+ "in": "path",
9456
+ "required": true,
9457
+ "description": "The unique identifier of the subscription.",
9458
+ "example": "78058918-9746-4280-9b9b-1bd5115eec6e",
9459
+ "schema": {
9460
+ "type": "string",
9461
+ "format": "uuid"
9462
+ }
9463
+ }
9464
+ ],
8565
9465
  "responses": {
8566
9466
  "200": {
8567
- "description": "The proposed update was priced successfully; no changes were applied.",
9467
+ "description": "The retention configuration for this subscription.",
8568
9468
  "content": {
8569
9469
  "application/json": {
8570
9470
  "schema": {
8571
- "$ref": "#/components/schemas/SubscriptionUpdatePreviewResponse"
9471
+ "$ref": "#/components/schemas/RetentionOffersResponse"
8572
9472
  },
8573
9473
  "example": {
8574
- "currency": "USD",
8575
- "recurringAmount": 50,
8576
- "recurringAmountUnits": 5000,
8577
- "amountChargedImmediately": 39.5,
8578
- "amountChargedImmediatelyUnits": 3950,
8579
- "nextInvoice": {
8580
- "amountDue": 39.5,
8581
- "amountDueUnits": 3950,
8582
- "nextPaymentAttempt": "2026-09-01T00:00:00Z",
8583
- "lineItems": [
8584
- {
8585
- "description": "Unused time on Pro after 12 Aug 2026",
8586
- "amount": -10.5,
8587
- "amountUnits": -1050
8588
- },
8589
- {
8590
- "description": "Remaining time on Enterprise after 12 Aug 2026",
8591
- "amount": 50,
8592
- "amountUnits": 5000
9474
+ "enabled": true,
9475
+ "writtenFeedback": {
9476
+ "enabled": true,
9477
+ "question": "What could we have done better?"
9478
+ },
9479
+ "reasons": [
9480
+ {
9481
+ "reason": "TOO_EXPENSIVE",
9482
+ "offer": {
9483
+ "type": "DISCOUNT",
9484
+ "percentageOff": 20,
9485
+ "billingCycles": 3,
9486
+ "eligible": true,
9487
+ "ineligibleReason": null
8593
9488
  }
8594
- ]
8595
- }
9489
+ },
9490
+ {
9491
+ "reason": "UNUSED",
9492
+ "offer": {
9493
+ "type": "PAUSE",
9494
+ "durations": [
9495
+ {
9496
+ "months": 1,
9497
+ "billingResumesOn": "2026-12-01"
9498
+ },
9499
+ {
9500
+ "months": 3,
9501
+ "billingResumesOn": "2027-02-01"
9502
+ }
9503
+ ],
9504
+ "eligible": true,
9505
+ "ineligibleReason": null
9506
+ }
9507
+ },
9508
+ {
9509
+ "reason": "CUSTOMER_SERVICE",
9510
+ "offer": {
9511
+ "type": "SUPPORT",
9512
+ "url": "https://cal.com/acme/15min",
9513
+ "eligible": true,
9514
+ "ineligibleReason": null
9515
+ }
9516
+ },
9517
+ {
9518
+ "reason": "MISSING_FEATURES",
9519
+ "offer": null
9520
+ },
9521
+ {
9522
+ "reason": "SWITCHED_SERVICE",
9523
+ "offer": null
9524
+ },
9525
+ {
9526
+ "reason": "LOW_QUALITY",
9527
+ "offer": null
9528
+ },
9529
+ {
9530
+ "reason": "TOO_COMPLEX",
9531
+ "offer": null
9532
+ },
9533
+ {
9534
+ "reason": "OTHER",
9535
+ "offer": null
9536
+ }
9537
+ ]
8596
9538
  }
8597
9539
  }
8598
9540
  }
8599
9541
  },
8600
9542
  "400": {
8601
- "description": "Bad Request - Invalid subscription update, pricing configuration, or payment-provider preview error.",
9543
+ "description": "The subscription was not found, is not active, or the offer could not be applied. `detail` explains why.",
8602
9544
  "content": {
8603
9545
  "application/json": {
8604
9546
  "schema": {
8605
- "$ref": "#/components/schemas/DetailErrorResponse"
9547
+ "type": "object",
9548
+ "properties": {
9549
+ "detail": {
9550
+ "type": "string"
9551
+ }
9552
+ }
8606
9553
  },
8607
9554
  "example": {
8608
- "detail": "Subscription does not exists"
9555
+ "detail": "This offer has already been used on this subscription."
8609
9556
  }
8610
9557
  }
8611
9558
  }
@@ -8613,14 +9560,14 @@
8613
9560
  }
8614
9561
  }
8615
9562
  },
8616
- "/subscriptions/{subscriptionId}/cancel/": {
9563
+ "/subscriptions/{subscriptionId}/retention/accept/": {
8617
9564
  "post": {
8618
9565
  "tags": [
8619
9566
  "Subscriptions"
8620
9567
  ],
8621
- "summary": "Cancel a subscription",
8622
- "description": "Cancels an active subscription for a customer.",
8623
- "operationId": "cancelSubscription",
9568
+ "summary": "Accept a retention offer",
9569
+ "description": "Applies the retention offer a customer accepted instead of cancelling.\n\nPass the cancellation reason the customer picked and the offer it maps to. `offerType` has to be the offer configured for that reason in the dashboard retention settings; any other pairing is rejected with `400`. Eligibility is checked again at this point, so an offer that was eligible when you fetched it can still be refused if, for example, the subscription was paused or scheduled to cancel in between.\n\nWhat happens depends on the offer:\n\n- `DISCOUNT` creates a single-use coupon for the configured percentage and billing cycles and attaches it to the subscription. The response includes the discounted amount and when the discount ends.\n- `PAUSE` pauses the subscription for `pauseMonths`, which must be one of the durations returned by [Get retention offers](/api-reference/subscriptions/get-retention-offers). Billing and access resume on the returned date, exactly as a merchant-initiated pause would.\n- `SUPPORT` records that the customer took the support offer and returns the configured support URL to send them to. Nothing changes on the subscription.\n\nEvery acceptance is recorded against the subscription and counted by the organization's offer repeat policy, so a customer cannot stack discounts or pause indefinitely by reopening the cancellation flow.",
9570
+ "operationId": "acceptRetentionOffer",
8624
9571
  "x-mint": {
8625
9572
  "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>"
8626
9573
  },
@@ -8629,7 +9576,7 @@
8629
9576
  "name": "subscriptionId",
8630
9577
  "in": "path",
8631
9578
  "required": true,
8632
- "description": "The unique identifier of the subscription to be cancelled. Example UUID from docs: 78058918-9746-4280-9b9b-1bd5115eec6e",
9579
+ "description": "The unique identifier of the subscription.",
8633
9580
  "example": "78058918-9746-4280-9b9b-1bd5115eec6e",
8634
9581
  "schema": {
8635
9582
  "type": "string",
@@ -8642,26 +9589,93 @@
8642
9589
  "content": {
8643
9590
  "application/json": {
8644
9591
  "schema": {
8645
- "$ref": "#/components/schemas/CancelSubscriptionRequest"
9592
+ "$ref": "#/components/schemas/AcceptRetentionOfferRequest"
8646
9593
  },
8647
9594
  "example": {
8648
- "cancellationType": "CURRENT_PERIOD_ENDS",
8649
- "cancellationFeedback": "TOO_EXPENSIVE",
8650
- "cancellationComment": "The plan no longer fits our budget."
9595
+ "offerType": "PAUSE",
9596
+ "cancellationFeedback": "UNUSED",
9597
+ "pauseMonths": 3
8651
9598
  }
8652
9599
  }
8653
9600
  }
8654
9601
  },
8655
9602
  "responses": {
8656
9603
  "200": {
8657
- "description": "Subscription cancellation processed successfully.",
9604
+ "description": "The offer was applied. The fields after `cancellationFeedback` depend on `offerType`.",
8658
9605
  "content": {
8659
9606
  "application/json": {
8660
9607
  "schema": {
8661
- "$ref": "#/components/schemas/CancelSubscriptionResponse"
9608
+ "$ref": "#/components/schemas/AcceptRetentionOfferResponse"
8662
9609
  },
8663
- "example": {
8664
- "message": "Subscription cancellation processed successfully."
9610
+ "examples": {
9611
+ "discount": {
9612
+ "summary": "Discount applied",
9613
+ "value": {
9614
+ "message": "Discount applied successfully",
9615
+ "subscriptionId": "78058918-9746-4280-9b9b-1bd5115eec6e",
9616
+ "offerType": "DISCOUNT",
9617
+ "cancellationFeedback": "TOO_EXPENSIVE",
9618
+ "percentageOff": 20,
9619
+ "billingCycles": 3,
9620
+ "appliesUntil": "2027-01-01T00:00:00Z",
9621
+ "originalAmount": "50.00",
9622
+ "discountedAmount": "40.00"
9623
+ }
9624
+ },
9625
+ "pause": {
9626
+ "summary": "Subscription paused",
9627
+ "value": {
9628
+ "message": "Subscription paused successfully",
9629
+ "subscriptionId": "78058918-9746-4280-9b9b-1bd5115eec6e",
9630
+ "offerType": "PAUSE",
9631
+ "cancellationFeedback": "UNUSED",
9632
+ "pauseMonths": 3,
9633
+ "resumesAt": "2027-02-01T00:00:00Z"
9634
+ }
9635
+ },
9636
+ "support": {
9637
+ "summary": "Support link issued",
9638
+ "value": {
9639
+ "message": "Support link issued",
9640
+ "subscriptionId": "78058918-9746-4280-9b9b-1bd5115eec6e",
9641
+ "offerType": "SUPPORT",
9642
+ "cancellationFeedback": "CUSTOMER_SERVICE",
9643
+ "url": "https://cal.com/acme/15min"
9644
+ }
9645
+ }
9646
+ }
9647
+ }
9648
+ }
9649
+ },
9650
+ "400": {
9651
+ "description": "Validation failed, the offer is not the one configured for this reason, the subscription is not eligible, or retention is switched off. Field errors are keyed by field name; everything else is reported in `detail`.",
9652
+ "content": {
9653
+ "application/json": {
9654
+ "schema": {
9655
+ "type": "object",
9656
+ "additionalProperties": true
9657
+ },
9658
+ "examples": {
9659
+ "notConfiguredForReason": {
9660
+ "summary": "Offer not mapped to this reason",
9661
+ "value": {
9662
+ "detail": "That offer is not available for this reason."
9663
+ }
9664
+ },
9665
+ "alreadyTaken": {
9666
+ "summary": "Repeat policy",
9667
+ "value": {
9668
+ "detail": "This offer has already been used on this subscription."
9669
+ }
9670
+ },
9671
+ "invalidField": {
9672
+ "summary": "Validation error",
9673
+ "value": {
9674
+ "offerType": [
9675
+ "offer_type must be one of ['DISCOUNT', 'PAUSE', 'SUPPORT', 'NONE']."
9676
+ ]
9677
+ }
9678
+ }
8665
9679
  }
8666
9680
  }
8667
9681
  }
@@ -11211,6 +12225,57 @@
11211
12225
  "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>"
11212
12226
  },
11213
12227
  "parameters": [
12228
+ {
12229
+ "name": "search",
12230
+ "in": "query",
12231
+ "required": false,
12232
+ "description": "Case-insensitive match on the endpoint name or URL.",
12233
+ "schema": {
12234
+ "type": "string"
12235
+ }
12236
+ },
12237
+ {
12238
+ "name": "status",
12239
+ "in": "query",
12240
+ "required": false,
12241
+ "description": "Only endpoints in this state.",
12242
+ "schema": {
12243
+ "type": "string",
12244
+ "enum": [
12245
+ "active",
12246
+ "failing",
12247
+ "disabled"
12248
+ ]
12249
+ }
12250
+ },
12251
+ {
12252
+ "name": "ordering",
12253
+ "in": "query",
12254
+ "required": false,
12255
+ "description": "`created_on` (default, newest first with `-`), `name` or `last_delivery`; prefix with `-` for descending.",
12256
+ "schema": {
12257
+ "type": "string"
12258
+ },
12259
+ "example": "-last_delivery"
12260
+ },
12261
+ {
12262
+ "name": "start_date",
12263
+ "in": "query",
12264
+ "required": false,
12265
+ "description": "Start of the period `deliveryCount` covers (default: 7 days ago). Same formats as the logs filters.",
12266
+ "schema": {
12267
+ "type": "string"
12268
+ }
12269
+ },
12270
+ {
12271
+ "name": "end_date",
12272
+ "in": "query",
12273
+ "required": false,
12274
+ "description": "End of the period `deliveryCount` covers (default: now).",
12275
+ "schema": {
12276
+ "type": "string"
12277
+ }
12278
+ },
11214
12279
  {
11215
12280
  "name": "page_size",
11216
12281
  "in": "query",
@@ -11254,7 +12319,7 @@
11254
12319
  "Webhook Endpoints"
11255
12320
  ],
11256
12321
  "summary": "Create a webhook endpoint",
11257
- "description": "Registers a new destination URL and its event subscriptions. A signing secret is generated automatically and returned once in the response.",
12322
+ "description": "Registers a new destination URL and its event subscriptions. A signing secret is generated automatically and returned in the response. `name` is optional and defaults to the URL's host.",
11258
12323
  "operationId": "createWebhookEndpoint",
11259
12324
  "x-mint": {
11260
12325
  "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>"
@@ -11393,6 +12458,191 @@
11393
12458
  }
11394
12459
  }
11395
12460
  }
12461
+ },
12462
+ "/integrations/lemon-squeezy/migrate/": {
12463
+ "post": {
12464
+ "tags": [
12465
+ "Imports"
12466
+ ],
12467
+ "summary": "Start a Lemon Squeezy import",
12468
+ "description": "Queues an import of a Lemon Squeezy store into your Kelviq organization: business profile, products and plans, customers, files, orders, renewals, discount codes, and license keys.\n\nThe import runs in the background. This request returns as soon as the job is queued, and a summary email is sent to the organization owner (or `reportEmail`) when the import ends. There is no status endpoint; the email is the only completion signal.\n\nAuthenticate with a Server API Key that was created by the organization **owner**. A key created by any other team member is refused with `403`.\n\nRunning the import again is safe: records already imported are skipped, new ones are added, and refunds made since are picked up. Subscriptions are imported as history. They keep renewing on Lemon Squeezy, and Kelviq does not charge them. Customers are not emailed and no webhooks fire for imported records.\n\nSee [Migrate from Lemon Squeezy](/guides/migrate-from-lemon-squeezy) for the full walkthrough.",
12469
+ "operationId": "startLemonSqueezyImport",
12470
+ "x-mint": {
12471
+ "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>"
12472
+ },
12473
+ "requestBody": {
12474
+ "required": true,
12475
+ "content": {
12476
+ "application/json": {
12477
+ "schema": {
12478
+ "$ref": "#/components/schemas/LemonSqueezyImportRequest"
12479
+ },
12480
+ "examples": {
12481
+ "full": {
12482
+ "summary": "Full import with defaults",
12483
+ "value": {
12484
+ "apiKey": "<lemon squeezy api key>",
12485
+ "storeId": "12345"
12486
+ }
12487
+ },
12488
+ "dryRun": {
12489
+ "summary": "Dry run, report to another address",
12490
+ "value": {
12491
+ "apiKey": "<lemon squeezy api key>",
12492
+ "storeId": "12345",
12493
+ "dryRun": true,
12494
+ "reportEmail": "ops@example.com"
12495
+ }
12496
+ },
12497
+ "rerun": {
12498
+ "summary": "Pick up new sales and refunds",
12499
+ "value": {
12500
+ "apiKey": "<lemon squeezy api key>",
12501
+ "storeId": "12345",
12502
+ "only": [
12503
+ "orders",
12504
+ "renewals"
12505
+ ]
12506
+ }
12507
+ }
12508
+ }
12509
+ }
12510
+ }
12511
+ },
12512
+ "responses": {
12513
+ "202": {
12514
+ "description": "The import is queued. Nothing has been imported yet.",
12515
+ "content": {
12516
+ "application/json": {
12517
+ "schema": {
12518
+ "$ref": "#/components/schemas/LemonSqueezyImportQueued"
12519
+ },
12520
+ "example": {
12521
+ "status": "queued",
12522
+ "taskId": "6f1c2f0e-8d3a-4a57-9b1e-2c1d5e7a9f10",
12523
+ "storeId": "12345",
12524
+ "storeName": "Acme Apps",
12525
+ "steps": [
12526
+ "store",
12527
+ "products",
12528
+ "customers",
12529
+ "files",
12530
+ "orders",
12531
+ "renewals",
12532
+ "discounts",
12533
+ "licenses"
12534
+ ],
12535
+ "orderType": "all",
12536
+ "dryRun": false,
12537
+ "reportEmail": "owner@example.com"
12538
+ }
12539
+ }
12540
+ }
12541
+ },
12542
+ "400": {
12543
+ "description": "A field is missing or invalid, `only` and `skip` leave no step to run, Lemon Squeezy rejected the key or the store id, or the organization has no owner (returned under `error`). Read whichever key is present: field names, `nonFieldErrors`, or `error`. Errors inside `only` and `skip` are keyed by the position of the bad item.",
12544
+ "content": {
12545
+ "application/json": {
12546
+ "schema": {
12547
+ "type": "object"
12548
+ },
12549
+ "examples": {
12550
+ "fields": {
12551
+ "summary": "Field validation",
12552
+ "value": {
12553
+ "apiKey": [
12554
+ "This field is required."
12555
+ ],
12556
+ "storeId": [
12557
+ "This value does not match the required pattern."
12558
+ ],
12559
+ "only": {
12560
+ "0": [
12561
+ "\"x\" is not a valid choice."
12562
+ ]
12563
+ }
12564
+ }
12565
+ },
12566
+ "noSteps": {
12567
+ "summary": "No step left to run",
12568
+ "value": {
12569
+ "nonFieldErrors": [
12570
+ "only / skip leave no step to run."
12571
+ ]
12572
+ }
12573
+ },
12574
+ "rejected": {
12575
+ "summary": "Lemon Squeezy rejected the request",
12576
+ "value": {
12577
+ "error": "Lemon Squeezy rejected the API key or the store id."
12578
+ }
12579
+ },
12580
+ "storeNotFound": {
12581
+ "summary": "Store not found for this key",
12582
+ "value": {
12583
+ "error": "Lemon Squeezy store 9 was not found for this API key."
12584
+ }
12585
+ }
12586
+ }
12587
+ }
12588
+ }
12589
+ },
12590
+ "403": {
12591
+ "description": "The `Authorization` header is missing, the key is not a valid Server API Key, or the key was not created by the organization owner. A missing or wrong key returns `403`, not `401`.",
12592
+ "content": {
12593
+ "application/json": {
12594
+ "schema": {
12595
+ "type": "object"
12596
+ },
12597
+ "examples": {
12598
+ "notOwner": {
12599
+ "summary": "Key not created by the owner",
12600
+ "value": {
12601
+ "detail": "Use a server key created by the organization owner."
12602
+ }
12603
+ },
12604
+ "invalid": {
12605
+ "summary": "Invalid key",
12606
+ "value": {
12607
+ "detail": "Invalid Bearer Token"
12608
+ }
12609
+ },
12610
+ "missing": {
12611
+ "summary": "No Authorization header",
12612
+ "value": {
12613
+ "detail": "Authentication credentials were not provided."
12614
+ }
12615
+ }
12616
+ }
12617
+ }
12618
+ }
12619
+ },
12620
+ "409": {
12621
+ "description": "An import is already running for the organization. If no report arrives and requests keep returning `409`, contact [hi@kelviq.com](mailto:hi@kelviq.com) with the `taskId` from the `202` response.",
12622
+ "content": {
12623
+ "application/json": {
12624
+ "schema": {
12625
+ "type": "object"
12626
+ },
12627
+ "examples": {
12628
+ "running": {
12629
+ "summary": "Already running",
12630
+ "value": {
12631
+ "error": "A Lemon Squeezy import is already running for this organization. Its summary will be emailed when it finishes."
12632
+ }
12633
+ }
12634
+ }
12635
+ }
12636
+ }
12637
+ },
12638
+ "429": {
12639
+ "description": "Organization rate limit exceeded."
12640
+ },
12641
+ "503": {
12642
+ "description": "The import could not be queued. Try again."
12643
+ }
12644
+ }
12645
+ }
11396
12646
  }
11397
12647
  }
11398
12648
  }