@kelviq/cli 0.2.0 → 0.3.1

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.
@@ -80,6 +80,14 @@
80
80
  "name": "Invoices",
81
81
  "description": "Invoices generated for orders and subscription billing cycles."
82
82
  },
83
+ {
84
+ "name": "Discounts",
85
+ "description": "Discount codes (coupons) that can be applied to products and plans at checkout."
86
+ },
87
+ {
88
+ "name": "Webhook Endpoints",
89
+ "description": "Configure the destination URLs and event subscriptions that receive webhook deliveries."
90
+ },
83
91
  {
84
92
  "name": "Webhooks",
85
93
  "description": "Delivery logs for webhook events sent to your configured endpoints."
@@ -424,6 +432,12 @@
424
432
  "description": "A comma-separated list of plan identifiers to display on the checkout page.",
425
433
  "example": "plan-pro-monthly,plan-pro-yearly"
426
434
  },
435
+ "billingPeriodsEnabled": {
436
+ "type": "string",
437
+ "nullable": true,
438
+ "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
+ "example": "MONTHLY,YEARLY"
440
+ },
427
441
  "currencyCode": {
428
442
  "type": "string",
429
443
  "nullable": true,
@@ -458,6 +472,13 @@
458
472
  "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.",
459
473
  "example": "WELCOME20"
460
474
  },
475
+ "email": {
476
+ "type": "string",
477
+ "format": "email",
478
+ "nullable": true,
479
+ "description": "The email address to pre-fill on the checkout page. Set lockEmail to true to prevent the customer from changing it.",
480
+ "example": "customer@example.com"
481
+ },
461
482
  "lockEmail": {
462
483
  "type": "boolean",
463
484
  "nullable": true,
@@ -1170,7 +1191,7 @@
1170
1191
  "minimum": 0,
1171
1192
  "exclusiveMinimum": true,
1172
1193
  "nullable": true,
1173
- "description": "Optional custom amount to charge, expressed in the currency's major unit (for example, `49.99` USD). Overrides the plan's configured one-time price. `currencyCode` is required when this field is provided, and Stripe's minimum charge for that currency applies.",
1194
+ "description": "Optional custom amount to charge, expressed in the currency's major unit (for example, `49.99` USD). Overrides the plan's configured one-time price. `currencyCode` is required when this field is provided, and minimum charge for that currency applies.",
1174
1195
  "example": 49.99
1175
1196
  },
1176
1197
  "taxBehavior": {
@@ -3324,7 +3345,7 @@
3324
3345
  "type": "object",
3325
3346
  "readOnly": true,
3326
3347
  "additionalProperties": true,
3327
- "description": "Provider-side identifiers (e.g. `stripeProductId`).",
3348
+ "description": "Provider-side identifiers.",
3328
3349
  "example": {
3329
3350
  "stripeProductId": "prod_ABC123"
3330
3351
  }
@@ -5658,7 +5679,7 @@
5658
5679
  "type": "string",
5659
5680
  "format": "date-time",
5660
5681
  "nullable": true,
5661
- "description": "When Stripe will next retry collection, if a retry is scheduled.",
5682
+ "description": "Date time when next retry is scheduled.",
5662
5683
  "example": null
5663
5684
  },
5664
5685
  "failureDetails": {
@@ -5767,269 +5788,433 @@
5767
5788
  }
5768
5789
  }
5769
5790
  }
5770
- }
5771
- }
5772
- },
5773
- "security": [
5774
- {
5775
- "bearerAuth": []
5776
- }
5777
- ],
5778
- "paths": {
5779
- "/customers/": {
5780
- "get": {
5781
- "tags": [
5782
- "Customers"
5783
- ],
5784
- "summary": "List customers",
5785
- "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`.",
5786
- "operationId": "listCustomers",
5787
- "x-mint": {
5788
- "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>"
5789
- },
5790
- "parameters": [
5791
- {
5792
- "name": "search",
5793
- "in": "query",
5794
- "required": false,
5795
- "description": "Free-text search across the customer's `name`, `email` and `customerId`.",
5796
- "schema": {
5797
- "type": "string"
5798
- }
5799
- },
5800
- {
5801
- "name": "page_size",
5802
- "in": "query",
5803
- "required": false,
5804
- "description": "Number of results to return per page. Defaults to 10, maximum 100.",
5805
- "schema": {
5806
- "type": "integer",
5807
- "minimum": 1,
5808
- "maximum": 100
5809
- }
5791
+ },
5792
+ "DiscountAppliesToProduct": {
5793
+ "type": "object",
5794
+ "properties": {
5795
+ "id": {
5796
+ "type": "string",
5797
+ "format": "uuid"
5810
5798
  },
5811
- {
5812
- "name": "page",
5813
- "in": "query",
5814
- "required": false,
5815
- "description": "The page number of results to return.",
5816
- "schema": {
5817
- "type": "integer"
5818
- }
5799
+ "name": {
5800
+ "type": "string"
5819
5801
  }
5820
- ],
5821
- "responses": {
5822
- "200": {
5823
- "description": "A paginated list of customers.",
5824
- "content": {
5825
- "application/json": {
5826
- "schema": {
5827
- "$ref": "#/components/schemas/CustomerListResponse"
5828
- },
5829
- "example": {
5830
- "count": 1,
5831
- "next": null,
5832
- "previous": null,
5833
- "results": [
5834
- {
5835
- "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
5836
- "customerId": "unique-customer-id-123",
5837
- "name": "John Doe",
5838
- "email": "new.customer@example.com",
5839
- "details": {},
5840
- "metadata": {
5841
- "source": "sdk_import",
5842
- "priority": "high"
5843
- },
5844
- "billingAddress": {
5845
- "country": "IN",
5846
- "line1": "123 Main Street",
5847
- "line2": "Apt 4B",
5848
- "postalCode": "560001",
5849
- "city": "Bangalore",
5850
- "state": "Karnataka"
5851
- },
5852
- "createdOn": "2025-06-04T06:03:30.195790Z",
5853
- "modifiedOn": "2025-06-04T06:03:30.195831Z"
5854
- }
5855
- ]
5856
- }
5857
- }
5858
- }
5802
+ }
5803
+ },
5804
+ "DiscountAppliesToPlan": {
5805
+ "type": "object",
5806
+ "properties": {
5807
+ "identifier": {
5808
+ "type": "string"
5809
+ },
5810
+ "name": {
5811
+ "type": "string"
5859
5812
  }
5860
5813
  }
5861
5814
  },
5862
- "post": {
5863
- "tags": [
5864
- "Customers"
5865
- ],
5866
- "summary": "Create a customer",
5867
- "description": "Creates a new customer record within kelviq.",
5868
- "operationId": "createCustomer",
5869
- "x-mint": {
5870
- "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>"
5871
- },
5872
- "requestBody": {
5873
- "required": true,
5874
- "content": {
5875
- "application/json": {
5876
- "schema": {
5877
- "$ref": "#/components/schemas/CustomerCreateRequest"
5878
- }
5815
+ "DiscountAppliesTo": {
5816
+ "type": "object",
5817
+ "description": "One product (and optionally specific plans of that product) this discount is restricted to.",
5818
+ "properties": {
5819
+ "product": {
5820
+ "$ref": "#/components/schemas/DiscountAppliesToProduct"
5821
+ },
5822
+ "plans": {
5823
+ "type": "array",
5824
+ "items": {
5825
+ "$ref": "#/components/schemas/DiscountAppliesToPlan"
5879
5826
  }
5880
5827
  }
5881
- },
5882
- "responses": {
5883
- "201": {
5884
- "description": "Customer Created",
5885
- "content": {
5886
- "application/json": {
5887
- "schema": {
5888
- "$ref": "#/components/schemas/CustomerResponse"
5889
- },
5890
- "example": {
5891
- "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
5892
- "customerId": "unique-customer-id-123",
5893
- "name": "John Doe",
5894
- "email": "new.customer@example.com",
5895
- "details": {},
5896
- "metadata": {
5897
- "source": "sdk_import",
5898
- "priority": "high"
5899
- },
5900
- "billingAddress": {
5901
- "country": "IN",
5902
- "line1": "123 Main Street",
5903
- "line2": "Apt 4B",
5904
- "postalCode": "560001",
5905
- "city": "Bangalore",
5906
- "state": "Karnataka"
5907
- },
5908
- "createdOn": "2025-06-04T06:03:30.195790Z",
5909
- "modifiedOn": "2025-06-04T06:03:30.195831Z"
5910
- }
5911
- }
5828
+ }
5829
+ },
5830
+ "Discount": {
5831
+ "type": "object",
5832
+ "properties": {
5833
+ "id": {
5834
+ "type": "string",
5835
+ "format": "uuid",
5836
+ "example": "b3f1a2c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c"
5837
+ },
5838
+ "discountType": {
5839
+ "type": "string",
5840
+ "enum": [
5841
+ "PERCENTAGE",
5842
+ "FIXED_AMOUNT"
5843
+ ],
5844
+ "description": "PERCENTAGE discounts a percentage off the price. FIXED_AMOUNT discounts a flat amount off the total."
5845
+ },
5846
+ "amountOff": {
5847
+ "type": "string",
5848
+ "nullable": true,
5849
+ "description": "Amount to discount, in currency units (e.g. \"10.00\"). Set when `discountType` is FIXED_AMOUNT.",
5850
+ "example": "10.00"
5851
+ },
5852
+ "percentageOff": {
5853
+ "type": "integer",
5854
+ "nullable": true,
5855
+ "description": "Percentage to discount. Set when `discountType` is PERCENTAGE.",
5856
+ "example": 20
5857
+ },
5858
+ "currency": {
5859
+ "type": "string",
5860
+ "nullable": true,
5861
+ "description": "3-letter ISO currency code. Required when `discountType` is FIXED_AMOUNT.",
5862
+ "example": "usd"
5863
+ },
5864
+ "currencySymbol": {
5865
+ "type": "string",
5866
+ "example": "$"
5867
+ },
5868
+ "name": {
5869
+ "type": "string",
5870
+ "description": "Displayed on the customer's invoice.",
5871
+ "example": "Summer Sale"
5872
+ },
5873
+ "code": {
5874
+ "type": "string",
5875
+ "description": "Checkout discount code. Uppercase letters and numbers only.",
5876
+ "example": "SUMMER20"
5877
+ },
5878
+ "duration": {
5879
+ "type": "string",
5880
+ "enum": [
5881
+ "ONCE",
5882
+ "REPEATING",
5883
+ "FOREVER"
5884
+ ],
5885
+ "description": "How many billing cycles the discount applies for."
5886
+ },
5887
+ "durationInMonths": {
5888
+ "type": "integer",
5889
+ "nullable": true,
5890
+ "description": "Number of billing periods the discount applies for. Despite the field name, this counts billing cycles, not calendar months — e.g. 3 on a yearly plan means 3 years. Set when `duration` is REPEATING."
5891
+ },
5892
+ "redeemBy": {
5893
+ "type": "string",
5894
+ "format": "date-time",
5895
+ "nullable": true,
5896
+ "description": "UTC time after which this discount can no longer be redeemed."
5897
+ },
5898
+ "maxRedemptions": {
5899
+ "type": "integer",
5900
+ "nullable": true,
5901
+ "description": "Total number of times this code can be redeemed across all customers."
5902
+ },
5903
+ "timesRedeemed": {
5904
+ "type": "integer",
5905
+ "description": "Number of times this code has been redeemed so far."
5906
+ },
5907
+ "appliesTo": {
5908
+ "type": "array",
5909
+ "description": "Products/plans this discount is restricted to. Empty means the discount applies to all products.",
5910
+ "items": {
5911
+ "$ref": "#/components/schemas/DiscountAppliesTo"
5912
5912
  }
5913
+ },
5914
+ "isActive": {
5915
+ "type": "boolean"
5913
5916
  }
5914
5917
  }
5915
- }
5916
- },
5917
- "/customers/{customerId}/": {
5918
- "patch": {
5919
- "tags": [
5920
- "Customers"
5921
- ],
5922
- "summary": "Update a customer",
5923
- "description": "Performs a partial update on an existing customer using their client-defined `customerId`.",
5924
- "operationId": "updateCustomer",
5925
- "x-mint": {
5926
- "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>"
5927
- },
5928
- "parameters": [
5929
- {
5930
- "name": "customerId",
5931
- "in": "path",
5932
- "required": true,
5933
- "description": "The client-defined unique identifier for the customer.",
5934
- "example": "unique-customer-id-123",
5935
- "schema": {
5918
+ },
5919
+ "DiscountAppliesToRequestItem": {
5920
+ "type": "object",
5921
+ "properties": {
5922
+ "product": {
5923
+ "type": "string",
5924
+ "format": "uuid",
5925
+ "description": "Product ID this discount applies to."
5926
+ },
5927
+ "plans": {
5928
+ "type": "array",
5929
+ "items": {
5936
5930
  "type": "string"
5937
- }
5931
+ },
5932
+ "description": "Plan identifiers within the product to restrict the discount to. Omit or leave empty to apply to all plans of the product."
5938
5933
  }
5939
- ],
5940
- "requestBody": {
5941
- "required": true,
5942
- "content": {
5943
- "application/json": {
5944
- "schema": {
5945
- "$ref": "#/components/schemas/CustomerUpdateRequest"
5946
- }
5947
- }
5934
+ },
5935
+ "required": [
5936
+ "product"
5937
+ ]
5938
+ },
5939
+ "DiscountCreateRequest": {
5940
+ "type": "object",
5941
+ "properties": {
5942
+ "discountType": {
5943
+ "type": "string",
5944
+ "enum": [
5945
+ "PERCENTAGE",
5946
+ "FIXED_AMOUNT"
5947
+ ]
5948
+ },
5949
+ "amountOff": {
5950
+ "type": "string",
5951
+ "description": "Required (and only used) when `discountType` is FIXED_AMOUNT."
5952
+ },
5953
+ "percentageOff": {
5954
+ "type": "integer",
5955
+ "description": "Required (and only used) when `discountType` is PERCENTAGE."
5956
+ },
5957
+ "currency": {
5958
+ "type": "string",
5959
+ "description": "3-letter ISO currency code. Required when `discountType` is FIXED_AMOUNT."
5960
+ },
5961
+ "name": {
5962
+ "type": "string",
5963
+ "description": "Displayed on the customer's invoice."
5964
+ },
5965
+ "code": {
5966
+ "type": "string",
5967
+ "description": "Checkout discount code. Uppercase letters and numbers only, and must be unique among active discounts for the organization."
5968
+ },
5969
+ "duration": {
5970
+ "type": "string",
5971
+ "enum": [
5972
+ "ONCE",
5973
+ "REPEATING",
5974
+ "FOREVER"
5975
+ ],
5976
+ "default": "ONCE"
5977
+ },
5978
+ "durationInMonths": {
5979
+ "type": "integer",
5980
+ "description": "Number of billing periods the discount applies for. Despite the field name, this counts billing cycles, not calendar months — e.g. 3 on a yearly plan means 3 years. Required when `duration` is REPEATING."
5981
+ },
5982
+ "redeemBy": {
5983
+ "type": "string",
5984
+ "format": "date-time",
5985
+ "description": "UTC time after which this discount can no longer be redeemed. Must be in the future."
5986
+ },
5987
+ "maxRedemptions": {
5988
+ "type": "integer",
5989
+ "description": "Total number of times this code can be redeemed across all customers."
5990
+ },
5991
+ "appliesTo": {
5992
+ "type": "array",
5993
+ "items": {
5994
+ "$ref": "#/components/schemas/DiscountAppliesToRequestItem"
5995
+ },
5996
+ "description": "Restrict the discount to specific products/plans. Omit to apply to all products."
5948
5997
  }
5949
5998
  },
5950
- "responses": {
5951
- "200": {
5952
- "description": "Customer Updated",
5953
- "content": {
5954
- "application/json": {
5955
- "schema": {
5956
- "$ref": "#/components/schemas/CustomerResponse"
5957
- },
5958
- "example": {
5959
- "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
5960
- "customerId": "unique-customer-id-123",
5961
- "name": "Johnathan Doe",
5962
- "email": "new.customer@example.com",
5963
- "details": {},
5964
- "metadata": {
5965
- "source": "sdk_import",
5966
- "priority": "high",
5967
- "status": "active"
5968
- },
5969
- "billingAddress": {
5970
- "country": "IN",
5971
- "line1": "123 Main Street",
5972
- "line2": "Apt 4B",
5973
- "postalCode": "560001",
5974
- "city": "Bangalore",
5975
- "state": "Karnataka"
5976
- },
5977
- "createdOn": "2025-06-04T06:03:30.195790Z",
5978
- "modifiedOn": "2025-06-04T06:03:30.195831Z"
5979
- }
5980
- }
5999
+ "required": [
6000
+ "discountType",
6001
+ "name",
6002
+ "code"
6003
+ ]
6004
+ },
6005
+ "DiscountUpdateRequest": {
6006
+ "type": "object",
6007
+ "description": "Discounts only support toggling `isActive` after creation; every other field is immutable.",
6008
+ "properties": {
6009
+ "isActive": {
6010
+ "type": "boolean"
6011
+ }
6012
+ }
6013
+ },
6014
+ "DiscountListResponse": {
6015
+ "type": "object",
6016
+ "properties": {
6017
+ "count": {
6018
+ "type": "integer"
6019
+ },
6020
+ "next": {
6021
+ "type": "string",
6022
+ "format": "uri",
6023
+ "nullable": true
6024
+ },
6025
+ "previous": {
6026
+ "type": "string",
6027
+ "format": "uri",
6028
+ "nullable": true
6029
+ },
6030
+ "results": {
6031
+ "type": "array",
6032
+ "items": {
6033
+ "$ref": "#/components/schemas/Discount"
5981
6034
  }
5982
6035
  }
5983
6036
  }
5984
- }
5985
- },
5986
- "/checkout/": {
5987
- "post": {
5988
- "tags": [
5989
- "Checkout"
5990
- ],
5991
- "summary": "Create a checkout session",
5992
- "description": "Creates a new checkout session for a customer to proceed with a purchase or subscription.",
5993
- "operationId": "createCheckoutSession",
5994
- "x-mint": {
5995
- "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>"
5996
- },
5997
- "requestBody": {
5998
- "required": true,
5999
- "content": {
6000
- "application/json": {
6001
- "schema": {
6002
- "$ref": "#/components/schemas/CreateCheckoutSessionRequest"
6003
- }
6037
+ },
6038
+ "WebhookEndpoint": {
6039
+ "type": "object",
6040
+ "properties": {
6041
+ "id": {
6042
+ "type": "string",
6043
+ "format": "uuid",
6044
+ "example": "2f6b9e2a-7c1a-4a3e-8b6e-8e6f9a2c1d4a"
6045
+ },
6046
+ "url": {
6047
+ "type": "string",
6048
+ "format": "uri",
6049
+ "description": "Destination URL that webhook events are POSTed to.",
6050
+ "example": "https://example.com/webhooks/kelviq"
6051
+ },
6052
+ "enabled": {
6053
+ "type": "boolean",
6054
+ "description": "Disabled endpoints don't receive deliveries."
6055
+ },
6056
+ "events": {
6057
+ "type": "array",
6058
+ "description": "Event types this endpoint is subscribed to.",
6059
+ "items": {
6060
+ "type": "string",
6061
+ "enum": [
6062
+ "checkout.completed",
6063
+ "customer.created",
6064
+ "customer.updated",
6065
+ "order.created",
6066
+ "order.updated",
6067
+ "order.refunded",
6068
+ "subscription.created",
6069
+ "subscription.updated",
6070
+ "subscription.cancelled",
6071
+ "subscription.plan_changed",
6072
+ "subscription.trial_will_end",
6073
+ "invoice.created",
6074
+ "invoice.paid",
6075
+ "invoice.payment_failed",
6076
+ "refund.created",
6077
+ "refund.updated",
6078
+ "feature.usage_alert",
6079
+ "payment_method.created",
6080
+ "payment_method.updated",
6081
+ "payment_method.deleted"
6082
+ ]
6083
+ }
6084
+ },
6085
+ "secret": {
6086
+ "type": "string",
6087
+ "description": "Signing secret used to verify the `Kelviq-Signature` header on deliveries to this endpoint.",
6088
+ "readOnly": true
6089
+ }
6090
+ }
6091
+ },
6092
+ "WebhookEndpointCreateRequest": {
6093
+ "type": "object",
6094
+ "properties": {
6095
+ "url": {
6096
+ "type": "string",
6097
+ "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."
6099
+ },
6100
+ "events": {
6101
+ "type": "array",
6102
+ "items": {
6103
+ "type": "string",
6104
+ "enum": [
6105
+ "checkout.completed",
6106
+ "customer.created",
6107
+ "customer.updated",
6108
+ "order.created",
6109
+ "order.updated",
6110
+ "order.refunded",
6111
+ "subscription.created",
6112
+ "subscription.updated",
6113
+ "subscription.cancelled",
6114
+ "subscription.plan_changed",
6115
+ "subscription.trial_will_end",
6116
+ "invoice.created",
6117
+ "invoice.paid",
6118
+ "invoice.payment_failed",
6119
+ "refund.created",
6120
+ "refund.updated",
6121
+ "feature.usage_alert",
6122
+ "payment_method.created",
6123
+ "payment_method.updated",
6124
+ "payment_method.deleted"
6125
+ ]
6004
6126
  }
6127
+ },
6128
+ "enabled": {
6129
+ "type": "boolean",
6130
+ "default": true
6005
6131
  }
6006
6132
  },
6007
- "responses": {
6008
- "201": {
6009
- "description": "Checkout Session Created",
6010
- "content": {
6011
- "application/json": {
6012
- "schema": {
6013
- "$ref": "#/components/schemas/CreateCheckoutSessionResponse"
6014
- },
6015
- "example": {
6016
- "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
6017
- "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
6018
- }
6019
- }
6133
+ "required": [
6134
+ "url",
6135
+ "events"
6136
+ ]
6137
+ },
6138
+ "WebhookEndpointUpdateRequest": {
6139
+ "type": "object",
6140
+ "properties": {
6141
+ "url": {
6142
+ "type": "string",
6143
+ "format": "uri"
6144
+ },
6145
+ "events": {
6146
+ "type": "array",
6147
+ "items": {
6148
+ "type": "string",
6149
+ "enum": [
6150
+ "checkout.completed",
6151
+ "customer.created",
6152
+ "customer.updated",
6153
+ "order.created",
6154
+ "order.updated",
6155
+ "order.refunded",
6156
+ "subscription.created",
6157
+ "subscription.updated",
6158
+ "subscription.cancelled",
6159
+ "subscription.plan_changed",
6160
+ "subscription.trial_will_end",
6161
+ "invoice.created",
6162
+ "invoice.paid",
6163
+ "invoice.payment_failed",
6164
+ "refund.created",
6165
+ "refund.updated",
6166
+ "feature.usage_alert",
6167
+ "payment_method.created",
6168
+ "payment_method.updated",
6169
+ "payment_method.deleted"
6170
+ ]
6171
+ }
6172
+ },
6173
+ "enabled": {
6174
+ "type": "boolean"
6175
+ }
6176
+ }
6177
+ },
6178
+ "WebhookEndpointListResponse": {
6179
+ "type": "object",
6180
+ "properties": {
6181
+ "count": {
6182
+ "type": "integer"
6183
+ },
6184
+ "next": {
6185
+ "type": "string",
6186
+ "format": "uri",
6187
+ "nullable": true
6188
+ },
6189
+ "previous": {
6190
+ "type": "string",
6191
+ "format": "uri",
6192
+ "nullable": true
6193
+ },
6194
+ "results": {
6195
+ "type": "array",
6196
+ "items": {
6197
+ "$ref": "#/components/schemas/WebhookEndpoint"
6020
6198
  }
6021
6199
  }
6022
6200
  }
6023
6201
  }
6024
- },
6025
- "/checkout/sessions/": {
6202
+ }
6203
+ },
6204
+ "security": [
6205
+ {
6206
+ "bearerAuth": []
6207
+ }
6208
+ ],
6209
+ "paths": {
6210
+ "/customers/": {
6026
6211
  "get": {
6027
6212
  "tags": [
6028
- "Checkout Sessions"
6213
+ "Customers"
6029
6214
  ],
6030
- "summary": "List checkout sessions",
6031
- "description": "Returns a paginated list of checkout sessions for the authenticated organization, newest first.",
6032
- "operationId": "listCheckoutSessions",
6215
+ "summary": "List customers",
6216
+ "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`.",
6217
+ "operationId": "listCustomers",
6033
6218
  "x-mint": {
6034
6219
  "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>"
6035
6220
  },
@@ -6038,31 +6223,277 @@
6038
6223
  "name": "search",
6039
6224
  "in": "query",
6040
6225
  "required": false,
6041
- "description": "Search by session ID, customer name, email, customer ID, or product name.",
6226
+ "description": "Free-text search across the customer's `name`, `email` and `customerId`.",
6042
6227
  "schema": {
6043
6228
  "type": "string"
6044
6229
  }
6045
6230
  },
6046
6231
  {
6047
- "name": "status",
6232
+ "name": "page_size",
6048
6233
  "in": "query",
6049
6234
  "required": false,
6050
- "description": "Filter by session status.",
6235
+ "description": "Number of results to return per page. Defaults to 10, maximum 100.",
6051
6236
  "schema": {
6052
- "type": "string",
6053
- "example": "open"
6237
+ "type": "integer",
6238
+ "minimum": 1,
6239
+ "maximum": 100
6054
6240
  }
6055
6241
  },
6056
6242
  {
6057
- "name": "start_date",
6243
+ "name": "page",
6058
6244
  "in": "query",
6059
6245
  "required": false,
6060
- "description": "Include sessions created on or after this date.",
6246
+ "description": "The page number of results to return.",
6061
6247
  "schema": {
6062
- "type": "string",
6063
- "format": "date"
6248
+ "type": "integer"
6064
6249
  }
6065
- },
6250
+ }
6251
+ ],
6252
+ "responses": {
6253
+ "200": {
6254
+ "description": "A paginated list of customers.",
6255
+ "content": {
6256
+ "application/json": {
6257
+ "schema": {
6258
+ "$ref": "#/components/schemas/CustomerListResponse"
6259
+ },
6260
+ "example": {
6261
+ "count": 1,
6262
+ "next": null,
6263
+ "previous": null,
6264
+ "results": [
6265
+ {
6266
+ "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
6267
+ "customerId": "unique-customer-id-123",
6268
+ "name": "John Doe",
6269
+ "email": "new.customer@example.com",
6270
+ "details": {},
6271
+ "metadata": {
6272
+ "source": "sdk_import",
6273
+ "priority": "high"
6274
+ },
6275
+ "billingAddress": {
6276
+ "country": "IN",
6277
+ "line1": "123 Main Street",
6278
+ "line2": "Apt 4B",
6279
+ "postalCode": "560001",
6280
+ "city": "Bangalore",
6281
+ "state": "Karnataka"
6282
+ },
6283
+ "createdOn": "2025-06-04T06:03:30.195790Z",
6284
+ "modifiedOn": "2025-06-04T06:03:30.195831Z"
6285
+ }
6286
+ ]
6287
+ }
6288
+ }
6289
+ }
6290
+ }
6291
+ }
6292
+ },
6293
+ "post": {
6294
+ "tags": [
6295
+ "Customers"
6296
+ ],
6297
+ "summary": "Create a customer",
6298
+ "description": "Creates a new customer record within kelviq.",
6299
+ "operationId": "createCustomer",
6300
+ "x-mint": {
6301
+ "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>"
6302
+ },
6303
+ "requestBody": {
6304
+ "required": true,
6305
+ "content": {
6306
+ "application/json": {
6307
+ "schema": {
6308
+ "$ref": "#/components/schemas/CustomerCreateRequest"
6309
+ }
6310
+ }
6311
+ }
6312
+ },
6313
+ "responses": {
6314
+ "201": {
6315
+ "description": "Customer Created",
6316
+ "content": {
6317
+ "application/json": {
6318
+ "schema": {
6319
+ "$ref": "#/components/schemas/CustomerResponse"
6320
+ },
6321
+ "example": {
6322
+ "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
6323
+ "customerId": "unique-customer-id-123",
6324
+ "name": "John Doe",
6325
+ "email": "new.customer@example.com",
6326
+ "details": {},
6327
+ "metadata": {
6328
+ "source": "sdk_import",
6329
+ "priority": "high"
6330
+ },
6331
+ "billingAddress": {
6332
+ "country": "IN",
6333
+ "line1": "123 Main Street",
6334
+ "line2": "Apt 4B",
6335
+ "postalCode": "560001",
6336
+ "city": "Bangalore",
6337
+ "state": "Karnataka"
6338
+ },
6339
+ "createdOn": "2025-06-04T06:03:30.195790Z",
6340
+ "modifiedOn": "2025-06-04T06:03:30.195831Z"
6341
+ }
6342
+ }
6343
+ }
6344
+ }
6345
+ }
6346
+ }
6347
+ },
6348
+ "/customers/{customerId}/": {
6349
+ "patch": {
6350
+ "tags": [
6351
+ "Customers"
6352
+ ],
6353
+ "summary": "Update a customer",
6354
+ "description": "Performs a partial update on an existing customer using their client-defined `customerId`.",
6355
+ "operationId": "updateCustomer",
6356
+ "x-mint": {
6357
+ "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>"
6358
+ },
6359
+ "parameters": [
6360
+ {
6361
+ "name": "customerId",
6362
+ "in": "path",
6363
+ "required": true,
6364
+ "description": "The client-defined unique identifier for the customer.",
6365
+ "example": "unique-customer-id-123",
6366
+ "schema": {
6367
+ "type": "string"
6368
+ }
6369
+ }
6370
+ ],
6371
+ "requestBody": {
6372
+ "required": true,
6373
+ "content": {
6374
+ "application/json": {
6375
+ "schema": {
6376
+ "$ref": "#/components/schemas/CustomerUpdateRequest"
6377
+ }
6378
+ }
6379
+ }
6380
+ },
6381
+ "responses": {
6382
+ "200": {
6383
+ "description": "Customer Updated",
6384
+ "content": {
6385
+ "application/json": {
6386
+ "schema": {
6387
+ "$ref": "#/components/schemas/CustomerResponse"
6388
+ },
6389
+ "example": {
6390
+ "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
6391
+ "customerId": "unique-customer-id-123",
6392
+ "name": "Johnathan Doe",
6393
+ "email": "new.customer@example.com",
6394
+ "details": {},
6395
+ "metadata": {
6396
+ "source": "sdk_import",
6397
+ "priority": "high",
6398
+ "status": "active"
6399
+ },
6400
+ "billingAddress": {
6401
+ "country": "IN",
6402
+ "line1": "123 Main Street",
6403
+ "line2": "Apt 4B",
6404
+ "postalCode": "560001",
6405
+ "city": "Bangalore",
6406
+ "state": "Karnataka"
6407
+ },
6408
+ "createdOn": "2025-06-04T06:03:30.195790Z",
6409
+ "modifiedOn": "2025-06-04T06:03:30.195831Z"
6410
+ }
6411
+ }
6412
+ }
6413
+ }
6414
+ }
6415
+ }
6416
+ },
6417
+ "/checkout/": {
6418
+ "post": {
6419
+ "tags": [
6420
+ "Checkout"
6421
+ ],
6422
+ "summary": "Create a checkout session",
6423
+ "description": "Creates a new checkout session for a customer to proceed with a purchase or subscription.",
6424
+ "operationId": "createCheckoutSession",
6425
+ "x-mint": {
6426
+ "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>"
6427
+ },
6428
+ "requestBody": {
6429
+ "required": true,
6430
+ "content": {
6431
+ "application/json": {
6432
+ "schema": {
6433
+ "$ref": "#/components/schemas/CreateCheckoutSessionRequest"
6434
+ }
6435
+ }
6436
+ }
6437
+ },
6438
+ "responses": {
6439
+ "201": {
6440
+ "description": "Checkout Session Created",
6441
+ "content": {
6442
+ "application/json": {
6443
+ "schema": {
6444
+ "$ref": "#/components/schemas/CreateCheckoutSessionResponse"
6445
+ },
6446
+ "example": {
6447
+ "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
6448
+ "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
6449
+ }
6450
+ }
6451
+ }
6452
+ }
6453
+ }
6454
+ }
6455
+ },
6456
+ "/checkout/sessions/": {
6457
+ "get": {
6458
+ "tags": [
6459
+ "Checkout Sessions"
6460
+ ],
6461
+ "summary": "List checkout sessions",
6462
+ "description": "Returns a paginated list of checkout sessions for the authenticated organization, newest first.",
6463
+ "operationId": "listCheckoutSessions",
6464
+ "x-mint": {
6465
+ "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>"
6466
+ },
6467
+ "parameters": [
6468
+ {
6469
+ "name": "search",
6470
+ "in": "query",
6471
+ "required": false,
6472
+ "description": "Search by session ID, customer name, email, customer ID, or product name.",
6473
+ "schema": {
6474
+ "type": "string"
6475
+ }
6476
+ },
6477
+ {
6478
+ "name": "status",
6479
+ "in": "query",
6480
+ "required": false,
6481
+ "description": "Filter by session status.",
6482
+ "schema": {
6483
+ "type": "string",
6484
+ "example": "open"
6485
+ }
6486
+ },
6487
+ {
6488
+ "name": "start_date",
6489
+ "in": "query",
6490
+ "required": false,
6491
+ "description": "Include sessions created on or after this date.",
6492
+ "schema": {
6493
+ "type": "string",
6494
+ "format": "date"
6495
+ }
6496
+ },
6066
6497
  {
6067
6498
  "name": "end_date",
6068
6499
  "in": "query",
@@ -8279,6 +8710,16 @@
8279
8710
  },
8280
8711
  "example": "pro,enterprise"
8281
8712
  },
8713
+ {
8714
+ "name": "billing_periods_enabled",
8715
+ "in": "query",
8716
+ "required": false,
8717
+ "description": "Optional. Comma-separated list of billing periods to include in the response. Values are case-insensitive and are normalized to uppercase. When omitted, all available billing periods are returned.",
8718
+ "schema": {
8719
+ "type": "string"
8720
+ },
8721
+ "example": "MONTHLY,YEARLY"
8722
+ },
8282
8723
  {
8283
8724
  "name": "ip_address",
8284
8725
  "in": "query",
@@ -8588,112 +9029,695 @@
8588
9029
  "content": {
8589
9030
  "application/json": {
8590
9031
  "schema": {
8591
- "$ref": "#/components/schemas/ErrorResponse"
8592
- },
8593
- "example": {
8594
- "status": "Not found",
8595
- "message": "Product does not exist"
9032
+ "$ref": "#/components/schemas/ErrorResponse"
9033
+ },
9034
+ "example": {
9035
+ "status": "Not found",
9036
+ "message": "Product does not exist"
9037
+ }
9038
+ }
9039
+ }
9040
+ }
9041
+ }
9042
+ }
9043
+ },
9044
+ "/promotions": {
9045
+ "get": {
9046
+ "tags": [
9047
+ "Promotions"
9048
+ ],
9049
+ "summary": "Get promotions",
9050
+ "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>",
9051
+ "operationId": "getPromotion",
9052
+ "x-mint": {
9053
+ "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>"
9054
+ },
9055
+ "servers": [
9056
+ {
9057
+ "url": "https://edge.sandboxapi.kelviq.com/api/v1",
9058
+ "description": "Sandbox \u2014 Test environment"
9059
+ },
9060
+ {
9061
+ "url": "https://edge.api.kelviq.com/api/v1",
9062
+ "description": "Production \u2014 Live environment"
9063
+ }
9064
+ ],
9065
+ "parameters": [
9066
+ {
9067
+ "name": "promotion_id",
9068
+ "in": "query",
9069
+ "required": true,
9070
+ "description": "The promotion ID from the Kelviq dashboard.",
9071
+ "schema": {
9072
+ "type": "string"
9073
+ },
9074
+ "example": "promo_abc123"
9075
+ }
9076
+ ],
9077
+ "security": [
9078
+ {
9079
+ "bearerAuth": []
9080
+ }
9081
+ ],
9082
+ "responses": {
9083
+ "200": {
9084
+ "description": "Promotion data for the visitor's location",
9085
+ "content": {
9086
+ "application/json": {
9087
+ "schema": {
9088
+ "$ref": "#/components/schemas/PromotionResponse"
9089
+ },
9090
+ "example": {
9091
+ "country": "India",
9092
+ "countryCode": "IN",
9093
+ "percentage": 40,
9094
+ "code": "KQP5LHNZB1Z",
9095
+ "message": "",
9096
+ "widgets": [
9097
+ {
9098
+ "type": "BANNER",
9099
+ "backgroundColor": "#3182CE",
9100
+ "fontColor": "#F9F9F9",
9101
+ "highlightFontColor": "#DD5C64",
9102
+ "fontSize": "1rem",
9103
+ "unStyled": false,
9104
+ "addCloseIcon": false,
9105
+ "countryMessage": "Hello {country_flag} Hey! It looks like you are from <b>{country}</b>. Use code <b>\u201c{coupon_code}\u201d</b> to get <b>{discount_percentage}%</b> off.",
9106
+ "placement": "top",
9107
+ "borderRadius": "0"
9108
+ }
9109
+ ],
9110
+ "security": {
9111
+ "proxy": false,
9112
+ "crawler": false,
9113
+ "vpn": false,
9114
+ "tor": false,
9115
+ "relay": false
9116
+ }
9117
+ }
9118
+ }
9119
+ }
9120
+ },
9121
+ "401": {
9122
+ "description": "Unauthorized \u2014 missing or invalid API key"
9123
+ },
9124
+ "404": {
9125
+ "description": "Promotion not found"
9126
+ }
9127
+ }
9128
+ }
9129
+ },
9130
+ "/portal/session/": {
9131
+ "post": {
9132
+ "tags": [
9133
+ "Portal"
9134
+ ],
9135
+ "summary": "Create a portal session",
9136
+ "description": "Creates a new customer portal session, returning a token and URL to redirect the customer to their billing portal. The selected customer must have an email address because the signed session token is tied to that email.",
9137
+ "operationId": "createPortalSession",
9138
+ "x-mint": {
9139
+ "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>"
9140
+ },
9141
+ "security": [
9142
+ {
9143
+ "bearerAuth": []
9144
+ }
9145
+ ],
9146
+ "requestBody": {
9147
+ "required": true,
9148
+ "content": {
9149
+ "application/json": {
9150
+ "schema": {
9151
+ "$ref": "#/components/schemas/CreatePortalSessionRequest"
9152
+ }
9153
+ }
9154
+ }
9155
+ },
9156
+ "responses": {
9157
+ "200": {
9158
+ "description": "Portal Session Created",
9159
+ "content": {
9160
+ "application/json": {
9161
+ "schema": {
9162
+ "$ref": "#/components/schemas/CreatePortalSessionResponse"
9163
+ },
9164
+ "example": {
9165
+ "token": "cpt-4f7c5dc4-da9f-447b-d447-6266dc35ed6d:23fca530-adeb-4685-b3d5-9928c6d38275",
9166
+ "email": "geo@example.com",
9167
+ "customerPortalUrl": "https://www.kelviq.com/portal/aphelo/"
9168
+ }
9169
+ }
9170
+ }
9171
+ },
9172
+ "400": {
9173
+ "description": "Invalid customer identifier or the customer does not have an email address.",
9174
+ "content": {
9175
+ "application/json": {
9176
+ "schema": {
9177
+ "type": "object",
9178
+ "properties": {
9179
+ "customerId": {
9180
+ "type": "array",
9181
+ "items": {
9182
+ "type": "string"
9183
+ }
9184
+ }
9185
+ }
9186
+ },
9187
+ "examples": {
9188
+ "invalidCustomer": {
9189
+ "summary": "Customer not found",
9190
+ "value": {
9191
+ "customerId": [
9192
+ "Invalid customer id"
9193
+ ]
9194
+ }
9195
+ },
9196
+ "missingEmail": {
9197
+ "summary": "Customer has no email",
9198
+ "value": {
9199
+ "customerId": [
9200
+ "Customer does not have an email"
9201
+ ]
9202
+ }
9203
+ }
9204
+ }
9205
+ }
9206
+ }
9207
+ },
9208
+ "401": {
9209
+ "description": "Unauthorized \u2014 missing or invalid API key"
9210
+ }
9211
+ }
9212
+ }
9213
+ },
9214
+ "/catalog/products/": {
9215
+ "get": {
9216
+ "tags": [
9217
+ "Products"
9218
+ ],
9219
+ "summary": "List products",
9220
+ "description": "Returns a paginated list of all products in the organization's catalog. Archived products are excluded.",
9221
+ "operationId": "listCatalogProducts",
9222
+ "x-mint": {
9223
+ "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>"
9224
+ },
9225
+ "security": [
9226
+ {
9227
+ "bearerAuth": []
9228
+ }
9229
+ ],
9230
+ "parameters": [
9231
+ {
9232
+ "name": "search",
9233
+ "in": "query",
9234
+ "required": false,
9235
+ "description": "Free-text search across `name`, `identifier`, and `description`.",
9236
+ "example": "pro",
9237
+ "schema": {
9238
+ "type": "string"
9239
+ }
9240
+ },
9241
+ {
9242
+ "name": "page",
9243
+ "in": "query",
9244
+ "required": false,
9245
+ "description": "Page number for pagination.",
9246
+ "example": 1,
9247
+ "schema": {
9248
+ "type": "integer"
9249
+ }
9250
+ },
9251
+ {
9252
+ "name": "page_size",
9253
+ "in": "query",
9254
+ "required": false,
9255
+ "description": "Number of results per page. Defaults to 100, maximum 100.",
9256
+ "schema": {
9257
+ "type": "integer",
9258
+ "minimum": 1,
9259
+ "maximum": 100
9260
+ }
9261
+ }
9262
+ ],
9263
+ "responses": {
9264
+ "200": {
9265
+ "description": "Paginated list of products.",
9266
+ "content": {
9267
+ "application/json": {
9268
+ "schema": {
9269
+ "$ref": "#/components/schemas/PaginatedProducts"
9270
+ }
9271
+ }
9272
+ }
9273
+ },
9274
+ "401": {
9275
+ "description": "Unauthorized \u2014 missing or invalid API key"
9276
+ }
9277
+ }
9278
+ },
9279
+ "post": {
9280
+ "tags": [
9281
+ "Products"
9282
+ ],
9283
+ "summary": "Create a product",
9284
+ "description": "Creates a new product.",
9285
+ "operationId": "createCatalogProduct",
9286
+ "x-mint": {
9287
+ "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>"
9288
+ },
9289
+ "security": [
9290
+ {
9291
+ "bearerAuth": []
9292
+ }
9293
+ ],
9294
+ "requestBody": {
9295
+ "required": true,
9296
+ "content": {
9297
+ "application/json": {
9298
+ "schema": {
9299
+ "$ref": "#/components/schemas/ProductCreateRequest"
9300
+ }
9301
+ }
9302
+ }
9303
+ },
9304
+ "responses": {
9305
+ "201": {
9306
+ "description": "Product created.",
9307
+ "content": {
9308
+ "application/json": {
9309
+ "schema": {
9310
+ "$ref": "#/components/schemas/Product"
9311
+ },
9312
+ "example": {
9313
+ "id": "762f0098-a8ef-4eed-b08b-f02043771b76",
9314
+ "identifier": "parity-deals",
9315
+ "name": "ParityDeals",
9316
+ "description": "",
9317
+ "createdBy": "Geo Jacob",
9318
+ "modifiedOn": "2026-05-20T10:54:41.324224Z",
9319
+ "images": [
9320
+ {
9321
+ "id": "2e025341-0f78-42cc-b814-8f059ac53339",
9322
+ "name": "web-app-manifest-512x512.png",
9323
+ "image": "https://cdn.kelviq.com/media/staging/organizations/6/products/762f0098-a8ef-4eed-b08b-f02043771b76/f318dec5767c498482d9e5dffe8a3332/web-app-manifest-512x512.png",
9324
+ "ordering": 0,
9325
+ "thumbnail": true,
9326
+ "enabled": true
9327
+ }
9328
+ ],
9329
+ "taxCode": "saas"
9330
+ }
9331
+ }
9332
+ }
9333
+ },
9334
+ "401": {
9335
+ "description": "Unauthorized \u2014 missing or invalid API key"
9336
+ }
9337
+ }
9338
+ }
9339
+ },
9340
+ "/catalog/products/{pk}/": {
9341
+ "parameters": [
9342
+ {
9343
+ "name": "pk",
9344
+ "in": "path",
9345
+ "required": true,
9346
+ "description": "Product UUID.",
9347
+ "example": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
9348
+ "schema": {
9349
+ "type": "string",
9350
+ "format": "uuid"
9351
+ }
9352
+ }
9353
+ ],
9354
+ "get": {
9355
+ "tags": [
9356
+ "Products"
9357
+ ],
9358
+ "summary": "Retrieve a product",
9359
+ "description": "Fetches a product by ID along with its currently published plans.",
9360
+ "operationId": "retrieveCatalogProduct",
9361
+ "x-mint": {
9362
+ "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>"
9363
+ },
9364
+ "security": [
9365
+ {
9366
+ "bearerAuth": []
9367
+ }
9368
+ ],
9369
+ "responses": {
9370
+ "200": {
9371
+ "description": "Product details.",
9372
+ "content": {
9373
+ "application/json": {
9374
+ "schema": {
9375
+ "$ref": "#/components/schemas/ProductRetrieve"
9376
+ }
9377
+ }
9378
+ }
9379
+ },
9380
+ "404": {
9381
+ "description": "Product not found."
9382
+ },
9383
+ "401": {
9384
+ "description": "Unauthorized \u2014 missing or invalid API key"
9385
+ }
9386
+ }
9387
+ },
9388
+ "patch": {
9389
+ "tags": [
9390
+ "Products"
9391
+ ],
9392
+ "summary": "Update a product",
9393
+ "description": "Partially updates a product. New images and files can be attached by sending temporary S3 keys in `imageKeys` / `fileKeys`.",
9394
+ "operationId": "updateCatalogProduct",
9395
+ "x-mint": {
9396
+ "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>"
9397
+ },
9398
+ "security": [
9399
+ {
9400
+ "bearerAuth": []
9401
+ }
9402
+ ],
9403
+ "requestBody": {
9404
+ "required": true,
9405
+ "content": {
9406
+ "application/json": {
9407
+ "schema": {
9408
+ "$ref": "#/components/schemas/ProductUpdateRequest"
9409
+ }
9410
+ }
9411
+ }
9412
+ },
9413
+ "responses": {
9414
+ "200": {
9415
+ "description": "Updated product.",
9416
+ "content": {
9417
+ "application/json": {
9418
+ "schema": {
9419
+ "$ref": "#/components/schemas/Product"
9420
+ }
9421
+ }
9422
+ }
9423
+ },
9424
+ "401": {
9425
+ "description": "Unauthorized \u2014 missing or invalid API key"
9426
+ }
9427
+ }
9428
+ },
9429
+ "delete": {
9430
+ "tags": [
9431
+ "Products"
9432
+ ],
9433
+ "summary": "Archive a product",
9434
+ "description": "Soft-deletes (archives) the product. Already-archived products return 400.",
9435
+ "operationId": "deleteCatalogProduct",
9436
+ "x-mint": {
9437
+ "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>"
9438
+ },
9439
+ "security": [
9440
+ {
9441
+ "bearerAuth": []
9442
+ }
9443
+ ],
9444
+ "responses": {
9445
+ "204": {
9446
+ "description": "Product archived.",
9447
+ "content": {
9448
+ "application/json": {
9449
+ "schema": {
9450
+ "$ref": "#/components/schemas/MessageResponse"
9451
+ },
9452
+ "example": {
9453
+ "message": "Object deleted successfully."
9454
+ }
9455
+ }
9456
+ }
9457
+ },
9458
+ "400": {
9459
+ "description": "Already archived."
9460
+ },
9461
+ "401": {
9462
+ "description": "Unauthorized \u2014 missing or invalid API key"
9463
+ }
9464
+ }
9465
+ }
9466
+ },
9467
+ "/catalog/products/{pk}/settings/": {
9468
+ "parameters": [
9469
+ {
9470
+ "name": "pk",
9471
+ "in": "path",
9472
+ "required": true,
9473
+ "description": "Product UUID.",
9474
+ "example": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
9475
+ "schema": {
9476
+ "type": "string",
9477
+ "format": "uuid"
9478
+ }
9479
+ }
9480
+ ],
9481
+ "get": {
9482
+ "tags": [
9483
+ "Product Settings"
9484
+ ],
9485
+ "summary": "Retrieve product settings",
9486
+ "description": "Retrieves the VPN/TOR/proxy and presentation settings for a product. Settings are auto-created if they don't already exist.",
9487
+ "operationId": "getCatalogProductSettings",
9488
+ "x-mint": {
9489
+ "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>"
9490
+ },
9491
+ "security": [
9492
+ {
9493
+ "bearerAuth": []
9494
+ }
9495
+ ],
9496
+ "responses": {
9497
+ "200": {
9498
+ "description": "Product settings.",
9499
+ "content": {
9500
+ "application/json": {
9501
+ "schema": {
9502
+ "$ref": "#/components/schemas/ProductSettings"
9503
+ }
9504
+ }
9505
+ }
9506
+ },
9507
+ "401": {
9508
+ "description": "Unauthorized \u2014 missing or invalid API key"
9509
+ }
9510
+ }
9511
+ },
9512
+ "patch": {
9513
+ "tags": [
9514
+ "Product Settings"
9515
+ ],
9516
+ "summary": "Update product settings",
9517
+ "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.",
9518
+ "operationId": "updateCatalogProductSettings",
9519
+ "x-mint": {
9520
+ "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>"
9521
+ },
9522
+ "security": [
9523
+ {
9524
+ "bearerAuth": []
9525
+ }
9526
+ ],
9527
+ "requestBody": {
9528
+ "required": true,
9529
+ "content": {
9530
+ "application/json": {
9531
+ "schema": {
9532
+ "$ref": "#/components/schemas/ProductSettingsUpdateRequest"
9533
+ }
9534
+ }
9535
+ }
9536
+ },
9537
+ "responses": {
9538
+ "200": {
9539
+ "description": "Updated product settings.",
9540
+ "content": {
9541
+ "application/json": {
9542
+ "schema": {
9543
+ "$ref": "#/components/schemas/ProductSettings"
9544
+ }
9545
+ }
9546
+ }
9547
+ },
9548
+ "401": {
9549
+ "description": "Unauthorized \u2014 missing or invalid API key"
9550
+ }
9551
+ }
9552
+ }
9553
+ },
9554
+ "/catalog/products/{product_pk}/image/{pk}/": {
9555
+ "parameters": [
9556
+ {
9557
+ "name": "product_pk",
9558
+ "in": "path",
9559
+ "required": true,
9560
+ "description": "Parent product UUID.",
9561
+ "example": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
9562
+ "schema": {
9563
+ "type": "string",
9564
+ "format": "uuid"
9565
+ }
9566
+ },
9567
+ {
9568
+ "name": "pk",
9569
+ "in": "path",
9570
+ "required": true,
9571
+ "description": "Image UUID.",
9572
+ "example": "1f7e1b54-7c6f-4d7e-9a4f-2c9c2d8b9d31",
9573
+ "schema": {
9574
+ "type": "string",
9575
+ "format": "uuid"
9576
+ }
9577
+ }
9578
+ ],
9579
+ "patch": {
9580
+ "tags": [
9581
+ "Product Files"
9582
+ ],
9583
+ "summary": "Update a product image",
9584
+ "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.",
9585
+ "operationId": "updateCatalogProductImage",
9586
+ "x-mint": {
9587
+ "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>"
9588
+ },
9589
+ "security": [
9590
+ {
9591
+ "bearerAuth": []
9592
+ }
9593
+ ],
9594
+ "requestBody": {
9595
+ "required": true,
9596
+ "content": {
9597
+ "application/json": {
9598
+ "schema": {
9599
+ "$ref": "#/components/schemas/ProductImageUpdateRequest"
9600
+ }
9601
+ }
9602
+ }
9603
+ },
9604
+ "responses": {
9605
+ "200": {
9606
+ "description": "Updated product image.",
9607
+ "content": {
9608
+ "application/json": {
9609
+ "schema": {
9610
+ "$ref": "#/components/schemas/ProductImage"
8596
9611
  }
8597
9612
  }
8598
9613
  }
9614
+ },
9615
+ "401": {
9616
+ "description": "Unauthorized \u2014 missing or invalid API key"
9617
+ }
9618
+ }
9619
+ },
9620
+ "delete": {
9621
+ "tags": [
9622
+ "Product Files"
9623
+ ],
9624
+ "summary": "Delete a product image",
9625
+ "description": "Permanently deletes the product image record.",
9626
+ "operationId": "deleteCatalogProductImage",
9627
+ "x-mint": {
9628
+ "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>"
9629
+ },
9630
+ "security": [
9631
+ {
9632
+ "bearerAuth": []
9633
+ }
9634
+ ],
9635
+ "responses": {
9636
+ "204": {
9637
+ "description": "Image deleted."
9638
+ },
9639
+ "404": {
9640
+ "description": "Image not found."
9641
+ },
9642
+ "401": {
9643
+ "description": "Unauthorized \u2014 missing or invalid API key"
8599
9644
  }
8600
9645
  }
8601
9646
  }
8602
9647
  },
8603
- "/promotions": {
9648
+ "/catalog/features/": {
8604
9649
  "get": {
8605
9650
  "tags": [
8606
- "Promotions"
9651
+ "Features"
8607
9652
  ],
8608
- "summary": "Get promotions",
8609
- "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>",
8610
- "operationId": "getPromotion",
9653
+ "summary": "List features",
9654
+ "description": "Returns a paginated list of features for the organization. Archived features are excluded.",
9655
+ "operationId": "listCatalogFeatures",
8611
9656
  "x-mint": {
8612
9657
  "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>"
8613
9658
  },
8614
- "servers": [
8615
- {
8616
- "url": "https://edge.sandboxapi.kelviq.com/api/v1",
8617
- "description": "Sandbox \u2014 Test environment"
8618
- },
9659
+ "security": [
8619
9660
  {
8620
- "url": "https://edge.api.kelviq.com/api/v1",
8621
- "description": "Production \u2014 Live environment"
9661
+ "bearerAuth": []
8622
9662
  }
8623
9663
  ],
8624
9664
  "parameters": [
8625
9665
  {
8626
- "name": "promotion_id",
9666
+ "name": "search",
8627
9667
  "in": "query",
8628
- "required": true,
8629
- "description": "The promotion ID from the Kelviq dashboard.",
9668
+ "required": false,
9669
+ "description": "Free-text search across `name`, `identifier`, and `description`.",
9670
+ "example": "api",
8630
9671
  "schema": {
8631
9672
  "type": "string"
8632
- },
8633
- "example": "promo_abc123"
8634
- }
8635
- ],
8636
- "security": [
9673
+ }
9674
+ },
8637
9675
  {
8638
- "bearerAuth": []
9676
+ "name": "page",
9677
+ "in": "query",
9678
+ "required": false,
9679
+ "description": "Page number for pagination.",
9680
+ "example": 1,
9681
+ "schema": {
9682
+ "type": "integer",
9683
+ "minimum": 1
9684
+ }
9685
+ },
9686
+ {
9687
+ "name": "page_size",
9688
+ "in": "query",
9689
+ "required": false,
9690
+ "description": "Number of results per page. Defaults to 100, maximum 100.",
9691
+ "schema": {
9692
+ "type": "integer",
9693
+ "minimum": 1,
9694
+ "maximum": 100
9695
+ }
8639
9696
  }
8640
9697
  ],
8641
9698
  "responses": {
8642
9699
  "200": {
8643
- "description": "Promotion data for the visitor's location",
9700
+ "description": "Paginated list of features.",
8644
9701
  "content": {
8645
9702
  "application/json": {
8646
9703
  "schema": {
8647
- "$ref": "#/components/schemas/PromotionResponse"
8648
- },
8649
- "example": {
8650
- "country": "India",
8651
- "countryCode": "IN",
8652
- "percentage": 40,
8653
- "code": "KQP5LHNZB1Z",
8654
- "message": "",
8655
- "widgets": [
8656
- {
8657
- "type": "BANNER",
8658
- "backgroundColor": "#3182CE",
8659
- "fontColor": "#F9F9F9",
8660
- "highlightFontColor": "#DD5C64",
8661
- "fontSize": "1rem",
8662
- "unStyled": false,
8663
- "addCloseIcon": false,
8664
- "countryMessage": "Hello {country_flag} Hey! It looks like you are from <b>{country}</b>. Use code <b>\u201c{coupon_code}\u201d</b> to get <b>{discount_percentage}%</b> off.",
8665
- "placement": "top",
8666
- "borderRadius": "0"
8667
- }
8668
- ],
8669
- "security": {
8670
- "proxy": false,
8671
- "crawler": false,
8672
- "vpn": false,
8673
- "tor": false,
8674
- "relay": false
8675
- }
9704
+ "$ref": "#/components/schemas/PaginatedFeatures"
8676
9705
  }
8677
9706
  }
8678
9707
  }
8679
9708
  },
8680
9709
  "401": {
8681
9710
  "description": "Unauthorized \u2014 missing or invalid API key"
8682
- },
8683
- "404": {
8684
- "description": "Promotion not found"
8685
9711
  }
8686
9712
  }
8687
- }
8688
- },
8689
- "/portal/session/": {
9713
+ },
8690
9714
  "post": {
8691
9715
  "tags": [
8692
- "Portal"
9716
+ "Features"
8693
9717
  ],
8694
- "summary": "Create a portal session",
8695
- "description": "Creates a new customer portal session, returning a token and URL to redirect the customer to their billing portal. The selected customer must have an email address because the signed session token is tied to that email.",
8696
- "operationId": "createPortalSession",
9718
+ "summary": "Create a feature",
9719
+ "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`.",
9720
+ "operationId": "createCatalogFeature",
8697
9721
  "x-mint": {
8698
9722
  "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>"
8699
9723
  },
@@ -8707,77 +9731,121 @@
8707
9731
  "content": {
8708
9732
  "application/json": {
8709
9733
  "schema": {
8710
- "$ref": "#/components/schemas/CreatePortalSessionRequest"
9734
+ "$ref": "#/components/schemas/FeatureCreateRequest"
9735
+ }
9736
+ }
9737
+ }
9738
+ },
9739
+ "responses": {
9740
+ "201": {
9741
+ "description": "Feature created.",
9742
+ "content": {
9743
+ "application/json": {
9744
+ "schema": {
9745
+ "$ref": "#/components/schemas/CatalogFeature"
9746
+ }
8711
9747
  }
8712
9748
  }
9749
+ },
9750
+ "401": {
9751
+ "description": "Unauthorized \u2014 missing or invalid API key"
9752
+ }
9753
+ }
9754
+ }
9755
+ },
9756
+ "/catalog/features/{pk}/": {
9757
+ "parameters": [
9758
+ {
9759
+ "name": "pk",
9760
+ "in": "path",
9761
+ "required": true,
9762
+ "description": "Feature UUID.",
9763
+ "example": "3a3e92ab-90a3-4f43-8e87-9d4c8c5a9c01",
9764
+ "schema": {
9765
+ "type": "string",
9766
+ "format": "uuid"
8713
9767
  }
9768
+ }
9769
+ ],
9770
+ "get": {
9771
+ "tags": [
9772
+ "Features"
9773
+ ],
9774
+ "summary": "Retrieve a feature",
9775
+ "operationId": "retrieveCatalogFeature",
9776
+ "x-mint": {
9777
+ "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>"
8714
9778
  },
9779
+ "security": [
9780
+ {
9781
+ "bearerAuth": []
9782
+ }
9783
+ ],
8715
9784
  "responses": {
8716
9785
  "200": {
8717
- "description": "Portal Session Created",
9786
+ "description": "Feature details.",
8718
9787
  "content": {
8719
9788
  "application/json": {
8720
9789
  "schema": {
8721
- "$ref": "#/components/schemas/CreatePortalSessionResponse"
8722
- },
8723
- "example": {
8724
- "token": "cpt-4f7c5dc4-da9f-447b-d447-6266dc35ed6d:23fca530-adeb-4685-b3d5-9928c6d38275",
8725
- "email": "geo@example.com",
8726
- "customerPortalUrl": "https://www.kelviq.com/portal/aphelo/"
9790
+ "$ref": "#/components/schemas/CatalogFeature"
8727
9791
  }
8728
9792
  }
8729
9793
  }
8730
9794
  },
8731
- "400": {
8732
- "description": "Invalid customer identifier or the customer does not have an email address.",
9795
+ "404": {
9796
+ "description": "Feature not found."
9797
+ },
9798
+ "401": {
9799
+ "description": "Unauthorized \u2014 missing or invalid API key"
9800
+ }
9801
+ }
9802
+ },
9803
+ "delete": {
9804
+ "tags": [
9805
+ "Features"
9806
+ ],
9807
+ "summary": "Archive a feature",
9808
+ "description": "Soft-deletes the feature and updates any published pricing tables that referenced it.",
9809
+ "operationId": "deleteCatalogFeature",
9810
+ "x-mint": {
9811
+ "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>"
9812
+ },
9813
+ "security": [
9814
+ {
9815
+ "bearerAuth": []
9816
+ }
9817
+ ],
9818
+ "responses": {
9819
+ "204": {
9820
+ "description": "Feature archived.",
8733
9821
  "content": {
8734
9822
  "application/json": {
8735
9823
  "schema": {
8736
- "type": "object",
8737
- "properties": {
8738
- "customerId": {
8739
- "type": "array",
8740
- "items": {
8741
- "type": "string"
8742
- }
8743
- }
8744
- }
9824
+ "$ref": "#/components/schemas/MessageResponse"
8745
9825
  },
8746
- "examples": {
8747
- "invalidCustomer": {
8748
- "summary": "Customer not found",
8749
- "value": {
8750
- "customerId": [
8751
- "Invalid customer id"
8752
- ]
8753
- }
8754
- },
8755
- "missingEmail": {
8756
- "summary": "Customer has no email",
8757
- "value": {
8758
- "customerId": [
8759
- "Customer does not have an email"
8760
- ]
8761
- }
8762
- }
9826
+ "example": {
9827
+ "message": "Object archived successfully."
8763
9828
  }
8764
9829
  }
8765
9830
  }
8766
9831
  },
9832
+ "400": {
9833
+ "description": "Already archived."
9834
+ },
8767
9835
  "401": {
8768
9836
  "description": "Unauthorized \u2014 missing or invalid API key"
8769
9837
  }
8770
9838
  }
8771
9839
  }
8772
9840
  },
8773
- "/catalog/products/": {
9841
+ "/catalog/plans/": {
8774
9842
  "get": {
8775
9843
  "tags": [
8776
- "Products"
9844
+ "Plans"
8777
9845
  ],
8778
- "summary": "List products",
8779
- "description": "Returns a paginated list of all products in the organization's catalog. Archived products are excluded.",
8780
- "operationId": "listCatalogProducts",
9846
+ "summary": "List plans",
9847
+ "description": "Returns one row per plan identifier, picking the most recent version for each. Archived plans, or plans on archived products, are excluded.",
9848
+ "operationId": "listCatalogPlans",
8781
9849
  "x-mint": {
8782
9850
  "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>"
8783
9851
  },
@@ -8787,16 +9855,6 @@
8787
9855
  }
8788
9856
  ],
8789
9857
  "parameters": [
8790
- {
8791
- "name": "search",
8792
- "in": "query",
8793
- "required": false,
8794
- "description": "Free-text search across `name`, `identifier`, and `description`.",
8795
- "example": "pro",
8796
- "schema": {
8797
- "type": "string"
8798
- }
8799
- },
8800
9858
  {
8801
9859
  "name": "page",
8802
9860
  "in": "query",
@@ -8804,7 +9862,8 @@
8804
9862
  "description": "Page number for pagination.",
8805
9863
  "example": 1,
8806
9864
  "schema": {
8807
- "type": "integer"
9865
+ "type": "integer",
9866
+ "minimum": 1
8808
9867
  }
8809
9868
  },
8810
9869
  {
@@ -8821,11 +9880,11 @@
8821
9880
  ],
8822
9881
  "responses": {
8823
9882
  "200": {
8824
- "description": "Paginated list of products.",
9883
+ "description": "Paginated list of plans.",
8825
9884
  "content": {
8826
9885
  "application/json": {
8827
9886
  "schema": {
8828
- "$ref": "#/components/schemas/PaginatedProducts"
9887
+ "$ref": "#/components/schemas/PaginatedPlans"
8829
9888
  }
8830
9889
  }
8831
9890
  }
@@ -8837,11 +9896,11 @@
8837
9896
  },
8838
9897
  "post": {
8839
9898
  "tags": [
8840
- "Products"
9899
+ "Plans"
8841
9900
  ],
8842
- "summary": "Create a product",
8843
- "description": "Creates a new product.",
8844
- "operationId": "createCatalogProduct",
9901
+ "summary": "Create a plan",
9902
+ "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.",
9903
+ "operationId": "createCatalogPlan",
8845
9904
  "x-mint": {
8846
9905
  "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>"
8847
9906
  },
@@ -8855,37 +9914,18 @@
8855
9914
  "content": {
8856
9915
  "application/json": {
8857
9916
  "schema": {
8858
- "$ref": "#/components/schemas/ProductCreateRequest"
9917
+ "$ref": "#/components/schemas/PlanCreateRequest"
8859
9918
  }
8860
9919
  }
8861
9920
  }
8862
9921
  },
8863
9922
  "responses": {
8864
9923
  "201": {
8865
- "description": "Product created.",
9924
+ "description": "Plan created.",
8866
9925
  "content": {
8867
9926
  "application/json": {
8868
9927
  "schema": {
8869
- "$ref": "#/components/schemas/Product"
8870
- },
8871
- "example": {
8872
- "id": "762f0098-a8ef-4eed-b08b-f02043771b76",
8873
- "identifier": "parity-deals",
8874
- "name": "ParityDeals",
8875
- "description": "",
8876
- "createdBy": "Geo Jacob",
8877
- "modifiedOn": "2026-05-20T10:54:41.324224Z",
8878
- "images": [
8879
- {
8880
- "id": "2e025341-0f78-42cc-b814-8f059ac53339",
8881
- "name": "web-app-manifest-512x512.png",
8882
- "image": "https://cdn.kelviq.com/media/staging/organizations/6/products/762f0098-a8ef-4eed-b08b-f02043771b76/f318dec5767c498482d9e5dffe8a3332/web-app-manifest-512x512.png",
8883
- "ordering": 0,
8884
- "thumbnail": true,
8885
- "enabled": true
8886
- }
8887
- ],
8888
- "taxCode": "saas"
9928
+ "$ref": "#/components/schemas/CatalogPlan"
8889
9929
  }
8890
9930
  }
8891
9931
  }
@@ -8896,27 +9936,36 @@
8896
9936
  }
8897
9937
  }
8898
9938
  },
8899
- "/catalog/products/{pk}/": {
9939
+ "/catalog/plans/{identifier}/": {
8900
9940
  "parameters": [
8901
9941
  {
8902
- "name": "pk",
9942
+ "name": "identifier",
8903
9943
  "in": "path",
8904
9944
  "required": true,
8905
- "description": "Product UUID.",
8906
- "example": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
9945
+ "description": "Plan identifier (slug). Stable across versions.",
9946
+ "example": "pro-monthly",
8907
9947
  "schema": {
8908
- "type": "string",
8909
- "format": "uuid"
9948
+ "type": "string"
9949
+ }
9950
+ },
9951
+ {
9952
+ "name": "version",
9953
+ "in": "query",
9954
+ "required": false,
9955
+ "description": "Specific version number to fetch / update. Defaults to the latest version.",
9956
+ "example": 2,
9957
+ "schema": {
9958
+ "type": "integer"
8910
9959
  }
8911
9960
  }
8912
9961
  ],
8913
9962
  "get": {
8914
9963
  "tags": [
8915
- "Products"
9964
+ "Plans"
8916
9965
  ],
8917
- "summary": "Retrieve a product",
8918
- "description": "Fetches a product by ID along with its currently published plans.",
8919
- "operationId": "retrieveCatalogProduct",
9966
+ "summary": "Retrieve a plan",
9967
+ "description": "Fetches a plan by identifier. Pass `?version=N` to fetch a specific version; otherwise the latest version is returned.",
9968
+ "operationId": "retrieveCatalogPlan",
8920
9969
  "x-mint": {
8921
9970
  "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>"
8922
9971
  },
@@ -8927,17 +9976,17 @@
8927
9976
  ],
8928
9977
  "responses": {
8929
9978
  "200": {
8930
- "description": "Product details.",
9979
+ "description": "Plan details.",
8931
9980
  "content": {
8932
9981
  "application/json": {
8933
9982
  "schema": {
8934
- "$ref": "#/components/schemas/ProductRetrieve"
9983
+ "$ref": "#/components/schemas/CatalogPlan"
8935
9984
  }
8936
9985
  }
8937
9986
  }
8938
9987
  },
8939
9988
  "404": {
8940
- "description": "Product not found."
9989
+ "description": "Plan not found."
8941
9990
  },
8942
9991
  "401": {
8943
9992
  "description": "Unauthorized \u2014 missing or invalid API key"
@@ -8946,11 +9995,11 @@
8946
9995
  },
8947
9996
  "patch": {
8948
9997
  "tags": [
8949
- "Products"
9998
+ "Plans"
8950
9999
  ],
8951
- "summary": "Update a product",
8952
- "description": "Partially updates a product. New images and files can be attached by sending temporary S3 keys in `imageKeys` / `fileKeys`.",
8953
- "operationId": "updateCatalogProduct",
10000
+ "summary": "Update a plan",
10001
+ "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.",
10002
+ "operationId": "updateCatalogPlan",
8954
10003
  "x-mint": {
8955
10004
  "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>"
8956
10005
  },
@@ -8964,18 +10013,18 @@
8964
10013
  "content": {
8965
10014
  "application/json": {
8966
10015
  "schema": {
8967
- "$ref": "#/components/schemas/ProductUpdateRequest"
10016
+ "$ref": "#/components/schemas/PlanUpdateRequest"
8968
10017
  }
8969
10018
  }
8970
10019
  }
8971
10020
  },
8972
10021
  "responses": {
8973
10022
  "200": {
8974
- "description": "Updated product.",
10023
+ "description": "Updated plan.",
8975
10024
  "content": {
8976
10025
  "application/json": {
8977
10026
  "schema": {
8978
- "$ref": "#/components/schemas/Product"
10027
+ "$ref": "#/components/schemas/CatalogPlan"
8979
10028
  }
8980
10029
  }
8981
10030
  }
@@ -8987,11 +10036,11 @@
8987
10036
  },
8988
10037
  "delete": {
8989
10038
  "tags": [
8990
- "Products"
10039
+ "Plans"
8991
10040
  ],
8992
- "summary": "Archive a product",
8993
- "description": "Soft-deletes (archives) the product. Already-archived products return 400.",
8994
- "operationId": "deleteCatalogProduct",
10041
+ "summary": "Archive a plan",
10042
+ "description": "Archives all versions of the plan (sets `isArchived=true`).",
10043
+ "operationId": "deleteCatalogPlan",
8995
10044
  "x-mint": {
8996
10045
  "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>"
8997
10046
  },
@@ -9002,14 +10051,14 @@
9002
10051
  ],
9003
10052
  "responses": {
9004
10053
  "204": {
9005
- "description": "Product archived.",
10054
+ "description": "Plan archived.",
9006
10055
  "content": {
9007
10056
  "application/json": {
9008
10057
  "schema": {
9009
10058
  "$ref": "#/components/schemas/MessageResponse"
9010
10059
  },
9011
10060
  "example": {
9012
- "message": "Object deleted successfully."
10061
+ "message": "Plan archived successfully."
9013
10062
  }
9014
10063
  }
9015
10064
  }
@@ -9023,58 +10072,26 @@
9023
10072
  }
9024
10073
  }
9025
10074
  },
9026
- "/catalog/products/{pk}/settings/": {
10075
+ "/catalog/plans/{identifier}/publish/": {
9027
10076
  "parameters": [
9028
10077
  {
9029
- "name": "pk",
10078
+ "name": "identifier",
9030
10079
  "in": "path",
9031
10080
  "required": true,
9032
- "description": "Product UUID.",
9033
- "example": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
10081
+ "description": "Plan identifier.",
10082
+ "example": "pro-monthly",
9034
10083
  "schema": {
9035
- "type": "string",
9036
- "format": "uuid"
10084
+ "type": "string"
9037
10085
  }
9038
10086
  }
9039
10087
  ],
9040
- "get": {
9041
- "tags": [
9042
- "Product Settings"
9043
- ],
9044
- "summary": "Retrieve product settings",
9045
- "description": "Retrieves the VPN/TOR/proxy and presentation settings for a product. Settings are auto-created if they don't already exist.",
9046
- "operationId": "getCatalogProductSettings",
9047
- "x-mint": {
9048
- "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>"
9049
- },
9050
- "security": [
9051
- {
9052
- "bearerAuth": []
9053
- }
9054
- ],
9055
- "responses": {
9056
- "200": {
9057
- "description": "Product settings.",
9058
- "content": {
9059
- "application/json": {
9060
- "schema": {
9061
- "$ref": "#/components/schemas/ProductSettings"
9062
- }
9063
- }
9064
- }
9065
- },
9066
- "401": {
9067
- "description": "Unauthorized \u2014 missing or invalid API key"
9068
- }
9069
- }
9070
- },
9071
- "patch": {
10088
+ "post": {
9072
10089
  "tags": [
9073
- "Product Settings"
10090
+ "Plans"
9074
10091
  ],
9075
- "summary": "Update product settings",
9076
- "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.",
9077
- "operationId": "updateCatalogProductSettings",
10092
+ "summary": "Publish a plan",
10093
+ "description": "Promotes the most recent draft version of the plan to `isLatest=true`, demotes the previous published version. Optionally migrates existing customers' features or pricing. Fails with 400 if no price exists or required currencies are missing.",
10094
+ "operationId": "publishCatalogPlan",
9078
10095
  "x-mint": {
9079
10096
  "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>"
9080
10097
  },
@@ -9084,105 +10101,61 @@
9084
10101
  }
9085
10102
  ],
9086
10103
  "requestBody": {
9087
- "required": true,
10104
+ "required": false,
9088
10105
  "content": {
9089
10106
  "application/json": {
9090
10107
  "schema": {
9091
- "$ref": "#/components/schemas/ProductSettingsUpdateRequest"
10108
+ "$ref": "#/components/schemas/PlanPublishRequest"
9092
10109
  }
9093
10110
  }
9094
10111
  }
9095
10112
  },
9096
10113
  "responses": {
9097
10114
  "200": {
9098
- "description": "Updated product settings.",
10115
+ "description": "Plan published.",
9099
10116
  "content": {
9100
10117
  "application/json": {
9101
10118
  "schema": {
9102
- "$ref": "#/components/schemas/ProductSettings"
10119
+ "$ref": "#/components/schemas/PlanPublishResponse"
10120
+ },
10121
+ "example": {
10122
+ "status": "published"
9103
10123
  }
9104
10124
  }
9105
10125
  }
9106
10126
  },
10127
+ "400": {
10128
+ "description": "No price exists, missing currency coverage, or already published."
10129
+ },
10130
+ "428": {
10131
+ "description": "Billing provider not authenticated."
10132
+ },
9107
10133
  "401": {
9108
10134
  "description": "Unauthorized \u2014 missing or invalid API key"
9109
10135
  }
9110
10136
  }
9111
10137
  }
9112
10138
  },
9113
- "/catalog/products/{product_pk}/image/{pk}/": {
10139
+ "/catalog/plans/{identifier}/discard/": {
9114
10140
  "parameters": [
9115
10141
  {
9116
- "name": "product_pk",
9117
- "in": "path",
9118
- "required": true,
9119
- "description": "Parent product UUID.",
9120
- "example": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
9121
- "schema": {
9122
- "type": "string",
9123
- "format": "uuid"
9124
- }
9125
- },
9126
- {
9127
- "name": "pk",
10142
+ "name": "identifier",
9128
10143
  "in": "path",
9129
10144
  "required": true,
9130
- "description": "Image UUID.",
9131
- "example": "1f7e1b54-7c6f-4d7e-9a4f-2c9c2d8b9d31",
10145
+ "description": "Plan identifier.",
10146
+ "example": "pro-monthly",
9132
10147
  "schema": {
9133
- "type": "string",
9134
- "format": "uuid"
10148
+ "type": "string"
9135
10149
  }
9136
10150
  }
9137
10151
  ],
9138
- "patch": {
9139
- "tags": [
9140
- "Product Files"
9141
- ],
9142
- "summary": "Update a product image",
9143
- "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.",
9144
- "operationId": "updateCatalogProductImage",
9145
- "x-mint": {
9146
- "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>"
9147
- },
9148
- "security": [
9149
- {
9150
- "bearerAuth": []
9151
- }
9152
- ],
9153
- "requestBody": {
9154
- "required": true,
9155
- "content": {
9156
- "application/json": {
9157
- "schema": {
9158
- "$ref": "#/components/schemas/ProductImageUpdateRequest"
9159
- }
9160
- }
9161
- }
9162
- },
9163
- "responses": {
9164
- "200": {
9165
- "description": "Updated product image.",
9166
- "content": {
9167
- "application/json": {
9168
- "schema": {
9169
- "$ref": "#/components/schemas/ProductImage"
9170
- }
9171
- }
9172
- }
9173
- },
9174
- "401": {
9175
- "description": "Unauthorized \u2014 missing or invalid API key"
9176
- }
9177
- }
9178
- },
9179
10152
  "delete": {
9180
10153
  "tags": [
9181
- "Product Files"
10154
+ "Plans"
9182
10155
  ],
9183
- "summary": "Delete a product image",
9184
- "description": "Permanently deletes the product image record.",
9185
- "operationId": "deleteCatalogProductImage",
10156
+ "summary": "Discard draft plan",
10157
+ "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.",
10158
+ "operationId": "discardCatalogPlanDraft",
9186
10159
  "x-mint": {
9187
10160
  "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>"
9188
10161
  },
@@ -9193,10 +10166,20 @@
9193
10166
  ],
9194
10167
  "responses": {
9195
10168
  "204": {
9196
- "description": "Image deleted."
10169
+ "description": "Draft discarded.",
10170
+ "content": {
10171
+ "application/json": {
10172
+ "schema": {
10173
+ "$ref": "#/components/schemas/MessageResponse"
10174
+ },
10175
+ "example": {
10176
+ "message": "Plan discarded successfully."
10177
+ }
10178
+ }
10179
+ }
9197
10180
  },
9198
- "404": {
9199
- "description": "Image not found."
10181
+ "400": {
10182
+ "description": "Plan is already published; cannot be discarded."
9200
10183
  },
9201
10184
  "401": {
9202
10185
  "description": "Unauthorized \u2014 missing or invalid API key"
@@ -9204,14 +10187,36 @@
9204
10187
  }
9205
10188
  }
9206
10189
  },
9207
- "/catalog/features/": {
10190
+ "/catalog/plans/{identifier}/prices/": {
10191
+ "parameters": [
10192
+ {
10193
+ "name": "identifier",
10194
+ "in": "path",
10195
+ "required": true,
10196
+ "description": "Plan identifier.",
10197
+ "example": "pro-monthly",
10198
+ "schema": {
10199
+ "type": "string"
10200
+ }
10201
+ },
10202
+ {
10203
+ "name": "version",
10204
+ "in": "query",
10205
+ "required": false,
10206
+ "description": "Optional plan version to scope the query to.",
10207
+ "example": 2,
10208
+ "schema": {
10209
+ "type": "integer"
10210
+ }
10211
+ }
10212
+ ],
9208
10213
  "get": {
9209
10214
  "tags": [
9210
- "Features"
10215
+ "Plans"
9211
10216
  ],
9212
- "summary": "List features",
9213
- "description": "Returns a paginated list of features for the organization. Archived features are excluded.",
9214
- "operationId": "listCatalogFeatures",
10217
+ "summary": "List plan prices",
10218
+ "description": "Returns the prices configured on the plan (one per currency), each with its full per-feature charge configuration.",
10219
+ "operationId": "listCatalogPlanPrices",
9215
10220
  "x-mint": {
9216
10221
  "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>"
9217
10222
  },
@@ -9220,47 +10225,13 @@
9220
10225
  "bearerAuth": []
9221
10226
  }
9222
10227
  ],
9223
- "parameters": [
9224
- {
9225
- "name": "search",
9226
- "in": "query",
9227
- "required": false,
9228
- "description": "Free-text search across `name`, `identifier`, and `description`.",
9229
- "example": "api",
9230
- "schema": {
9231
- "type": "string"
9232
- }
9233
- },
9234
- {
9235
- "name": "page",
9236
- "in": "query",
9237
- "required": false,
9238
- "description": "Page number for pagination.",
9239
- "example": 1,
9240
- "schema": {
9241
- "type": "integer",
9242
- "minimum": 1
9243
- }
9244
- },
9245
- {
9246
- "name": "page_size",
9247
- "in": "query",
9248
- "required": false,
9249
- "description": "Number of results per page. Defaults to 100, maximum 100.",
9250
- "schema": {
9251
- "type": "integer",
9252
- "minimum": 1,
9253
- "maximum": 100
9254
- }
9255
- }
9256
- ],
9257
10228
  "responses": {
9258
10229
  "200": {
9259
- "description": "Paginated list of features.",
10230
+ "description": "Paginated list of plan prices.",
9260
10231
  "content": {
9261
10232
  "application/json": {
9262
10233
  "schema": {
9263
- "$ref": "#/components/schemas/PaginatedFeatures"
10234
+ "$ref": "#/components/schemas/PaginatedPlanPrices"
9264
10235
  }
9265
10236
  }
9266
10237
  }
@@ -9269,14 +10240,28 @@
9269
10240
  "description": "Unauthorized \u2014 missing or invalid API key"
9270
10241
  }
9271
10242
  }
9272
- },
10243
+ }
10244
+ },
10245
+ "/catalog/plans/{identifier}/prices/bulk/": {
10246
+ "parameters": [
10247
+ {
10248
+ "name": "identifier",
10249
+ "in": "path",
10250
+ "required": true,
10251
+ "description": "Plan identifier.",
10252
+ "example": "pro-monthly",
10253
+ "schema": {
10254
+ "type": "string"
10255
+ }
10256
+ }
10257
+ ],
9273
10258
  "post": {
9274
10259
  "tags": [
9275
- "Features"
10260
+ "Plans"
9276
10261
  ],
9277
- "summary": "Create a feature",
9278
- "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`.",
9279
- "operationId": "createCatalogFeature",
10262
+ "summary": "Update plan prices",
10263
+ "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.",
10264
+ "operationId": "bulkSetCatalogPlanPrices",
9280
10265
  "x-mint": {
9281
10266
  "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>"
9282
10267
  },
@@ -9290,48 +10275,61 @@
9290
10275
  "content": {
9291
10276
  "application/json": {
9292
10277
  "schema": {
9293
- "$ref": "#/components/schemas/FeatureCreateRequest"
10278
+ "$ref": "#/components/schemas/PlanPriceBulkRequest"
9294
10279
  }
9295
10280
  }
9296
10281
  }
9297
10282
  },
9298
10283
  "responses": {
9299
- "201": {
9300
- "description": "Feature created.",
10284
+ "200": {
10285
+ "description": "Prices replaced.",
9301
10286
  "content": {
9302
10287
  "application/json": {
9303
10288
  "schema": {
9304
- "$ref": "#/components/schemas/CatalogFeature"
10289
+ "$ref": "#/components/schemas/PlanPriceBulkResponse"
9305
10290
  }
9306
10291
  }
9307
10292
  }
9308
10293
  },
10294
+ "400": {
10295
+ "description": "Validation error (duplicate currencies, invalid price configuration, etc.)."
10296
+ },
9309
10297
  "401": {
9310
10298
  "description": "Unauthorized \u2014 missing or invalid API key"
9311
10299
  }
9312
10300
  }
9313
10301
  }
9314
10302
  },
9315
- "/catalog/features/{pk}/": {
10303
+ "/catalog/plans/{identifier}/features/": {
9316
10304
  "parameters": [
9317
10305
  {
9318
- "name": "pk",
10306
+ "name": "identifier",
9319
10307
  "in": "path",
9320
10308
  "required": true,
9321
- "description": "Feature UUID.",
9322
- "example": "3a3e92ab-90a3-4f43-8e87-9d4c8c5a9c01",
10309
+ "description": "Plan identifier.",
10310
+ "example": "pro-monthly",
9323
10311
  "schema": {
9324
- "type": "string",
9325
- "format": "uuid"
10312
+ "type": "string"
10313
+ }
10314
+ },
10315
+ {
10316
+ "name": "version",
10317
+ "in": "query",
10318
+ "required": false,
10319
+ "description": "Plan version to scope the listing to (GET only).",
10320
+ "example": 2,
10321
+ "schema": {
10322
+ "type": "integer"
9326
10323
  }
9327
10324
  }
9328
10325
  ],
9329
10326
  "get": {
9330
10327
  "tags": [
9331
- "Features"
10328
+ "Plan Entitlements"
9332
10329
  ],
9333
- "summary": "Retrieve a feature",
9334
- "operationId": "retrieveCatalogFeature",
10330
+ "summary": "List plan entitlements",
10331
+ "description": "Returns the feature entitlements (with per-entitlement `details`) configured on the plan.",
10332
+ "operationId": "listCatalogPlanFeatures",
9335
10333
  "x-mint": {
9336
10334
  "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>"
9337
10335
  },
@@ -9342,30 +10340,27 @@
9342
10340
  ],
9343
10341
  "responses": {
9344
10342
  "200": {
9345
- "description": "Feature details.",
10343
+ "description": "Paginated list of entitlements.",
9346
10344
  "content": {
9347
10345
  "application/json": {
9348
10346
  "schema": {
9349
- "$ref": "#/components/schemas/CatalogFeature"
10347
+ "$ref": "#/components/schemas/PaginatedPlanFeatureEntitlements"
9350
10348
  }
9351
10349
  }
9352
10350
  }
9353
10351
  },
9354
- "404": {
9355
- "description": "Feature not found."
9356
- },
9357
10352
  "401": {
9358
10353
  "description": "Unauthorized \u2014 missing or invalid API key"
9359
10354
  }
9360
10355
  }
9361
10356
  },
9362
- "delete": {
10357
+ "post": {
9363
10358
  "tags": [
9364
- "Features"
10359
+ "Plan Entitlements"
9365
10360
  ],
9366
- "summary": "Archive a feature",
9367
- "description": "Soft-deletes the feature and updates any published pricing tables that referenced it.",
9368
- "operationId": "deleteCatalogFeature",
10361
+ "summary": "Add plan entitlements",
10362
+ "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.",
10363
+ "operationId": "addCatalogPlanFeatures",
9369
10364
  "x-mint": {
9370
10365
  "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>"
9371
10366
  },
@@ -9374,92 +10369,63 @@
9374
10369
  "bearerAuth": []
9375
10370
  }
9376
10371
  ],
10372
+ "requestBody": {
10373
+ "required": true,
10374
+ "content": {
10375
+ "application/json": {
10376
+ "schema": {
10377
+ "$ref": "#/components/schemas/PlanFeaturesCreateRequest"
10378
+ }
10379
+ }
10380
+ }
10381
+ },
9377
10382
  "responses": {
9378
- "204": {
9379
- "description": "Feature archived.",
10383
+ "201": {
10384
+ "description": "Entitlements added.",
9380
10385
  "content": {
9381
10386
  "application/json": {
9382
10387
  "schema": {
9383
- "$ref": "#/components/schemas/MessageResponse"
9384
- },
9385
- "example": {
9386
- "message": "Object archived successfully."
10388
+ "$ref": "#/components/schemas/CatalogPlan"
9387
10389
  }
9388
10390
  }
9389
10391
  }
9390
10392
  },
9391
- "400": {
9392
- "description": "Already archived."
9393
- },
9394
10393
  "401": {
9395
10394
  "description": "Unauthorized \u2014 missing or invalid API key"
9396
10395
  }
9397
10396
  }
9398
10397
  }
9399
10398
  },
9400
- "/catalog/plans/": {
9401
- "get": {
9402
- "tags": [
9403
- "Plans"
9404
- ],
9405
- "summary": "List plans",
9406
- "description": "Returns one row per plan identifier, picking the most recent version for each. Archived plans, or plans on archived products, are excluded.",
9407
- "operationId": "listCatalogPlans",
9408
- "x-mint": {
9409
- "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>"
9410
- },
9411
- "security": [
9412
- {
9413
- "bearerAuth": []
9414
- }
9415
- ],
9416
- "parameters": [
9417
- {
9418
- "name": "page",
9419
- "in": "query",
9420
- "required": false,
9421
- "description": "Page number for pagination.",
9422
- "example": 1,
9423
- "schema": {
9424
- "type": "integer",
9425
- "minimum": 1
9426
- }
9427
- },
9428
- {
9429
- "name": "page_size",
9430
- "in": "query",
9431
- "required": false,
9432
- "description": "Number of results per page. Defaults to 100, maximum 100.",
9433
- "schema": {
9434
- "type": "integer",
9435
- "minimum": 1,
9436
- "maximum": 100
9437
- }
10399
+ "/catalog/plans/{identifier}/features/{feature_id}/": {
10400
+ "parameters": [
10401
+ {
10402
+ "name": "identifier",
10403
+ "in": "path",
10404
+ "required": true,
10405
+ "description": "Plan identifier.",
10406
+ "example": "pro-monthly",
10407
+ "schema": {
10408
+ "type": "string"
9438
10409
  }
9439
- ],
9440
- "responses": {
9441
- "200": {
9442
- "description": "Paginated list of plans.",
9443
- "content": {
9444
- "application/json": {
9445
- "schema": {
9446
- "$ref": "#/components/schemas/PaginatedPlans"
9447
- }
9448
- }
9449
- }
9450
- },
9451
- "401": {
9452
- "description": "Unauthorized \u2014 missing or invalid API key"
10410
+ },
10411
+ {
10412
+ "name": "feature_id",
10413
+ "in": "path",
10414
+ "required": true,
10415
+ "description": "Feature identifier (slug, not UUID).",
10416
+ "example": "api-calls",
10417
+ "schema": {
10418
+ "type": "string"
9453
10419
  }
9454
10420
  }
9455
- },
9456
- "post": {
10421
+ ],
10422
+ "patch": {
9457
10423
  "tags": [
9458
- "Plans"
10424
+ "Plan Entitlements"
9459
10425
  ],
9460
- "summary": "Create a plan",
9461
- "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.",
9462
- "operationId": "createCatalogPlan",
10426
+ "summary": "Update plan entitlement",
10427
+ "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.",
10428
+ "operationId": "updateCatalogPlanFeature",
9463
10429
  "x-mint": {
9464
10430
  "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>"
9465
10431
  },
@@ -9473,18 +10439,21 @@
9473
10439
  "content": {
9474
10440
  "application/json": {
9475
10441
  "schema": {
9476
- "$ref": "#/components/schemas/PlanCreateRequest"
10442
+ "$ref": "#/components/schemas/PlanFeaturePatchRequest"
9477
10443
  }
9478
10444
  }
9479
10445
  }
9480
10446
  },
9481
10447
  "responses": {
9482
- "201": {
9483
- "description": "Plan created.",
10448
+ "200": {
10449
+ "description": "Entitlement updated.",
9484
10450
  "content": {
9485
10451
  "application/json": {
9486
- "schema": {
9487
- "$ref": "#/components/schemas/CatalogPlan"
10452
+ "example": {
10453
+ "details": {
10454
+ "value": 20000,
10455
+ "hasUnlimitedUsage": false
10456
+ }
9488
10457
  }
9489
10458
  }
9490
10459
  }
@@ -9493,38 +10462,14 @@
9493
10462
  "description": "Unauthorized \u2014 missing or invalid API key"
9494
10463
  }
9495
10464
  }
9496
- }
9497
- },
9498
- "/catalog/plans/{identifier}/": {
9499
- "parameters": [
9500
- {
9501
- "name": "identifier",
9502
- "in": "path",
9503
- "required": true,
9504
- "description": "Plan identifier (slug). Stable across versions.",
9505
- "example": "pro-monthly",
9506
- "schema": {
9507
- "type": "string"
9508
- }
9509
- },
9510
- {
9511
- "name": "version",
9512
- "in": "query",
9513
- "required": false,
9514
- "description": "Specific version number to fetch / update. Defaults to the latest version.",
9515
- "example": 2,
9516
- "schema": {
9517
- "type": "integer"
9518
- }
9519
- }
9520
- ],
9521
- "get": {
10465
+ },
10466
+ "delete": {
9522
10467
  "tags": [
9523
- "Plans"
10468
+ "Plan Entitlements"
9524
10469
  ],
9525
- "summary": "Retrieve a plan",
9526
- "description": "Fetches a plan by identifier. Pass `?version=N` to fetch a specific version; otherwise the latest version is returned.",
9527
- "operationId": "retrieveCatalogPlan",
10470
+ "summary": "Delete plan entitlement",
10471
+ "description": "Removes the named feature from the plan's entitlements. A new draft version is created if the latest is published.",
10472
+ "operationId": "deleteCatalogPlanFeature",
9528
10473
  "x-mint": {
9529
10474
  "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>"
9530
10475
  },
@@ -9534,31 +10479,56 @@
9534
10479
  }
9535
10480
  ],
9536
10481
  "responses": {
9537
- "200": {
9538
- "description": "Plan details.",
10482
+ "204": {
10483
+ "description": "Entitlement removed.",
9539
10484
  "content": {
9540
10485
  "application/json": {
9541
10486
  "schema": {
9542
- "$ref": "#/components/schemas/CatalogPlan"
10487
+ "$ref": "#/components/schemas/MessageResponse"
10488
+ },
10489
+ "example": {
10490
+ "message": "Entitlement deleted successfully."
9543
10491
  }
9544
10492
  }
9545
10493
  }
9546
10494
  },
9547
- "404": {
9548
- "description": "Plan not found."
9549
- },
9550
10495
  "401": {
9551
10496
  "description": "Unauthorized \u2014 missing or invalid API key"
9552
10497
  }
9553
10498
  }
9554
- },
10499
+ }
10500
+ },
10501
+ "/catalog/plans/{identifier}/file/{pk}/": {
10502
+ "parameters": [
10503
+ {
10504
+ "name": "identifier",
10505
+ "in": "path",
10506
+ "required": true,
10507
+ "description": "Plan identifier.",
10508
+ "example": "pro-monthly",
10509
+ "schema": {
10510
+ "type": "string"
10511
+ }
10512
+ },
10513
+ {
10514
+ "name": "pk",
10515
+ "in": "path",
10516
+ "required": true,
10517
+ "description": "Plan file UUID.",
10518
+ "example": "7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0",
10519
+ "schema": {
10520
+ "type": "string",
10521
+ "format": "uuid"
10522
+ }
10523
+ }
10524
+ ],
9555
10525
  "patch": {
9556
10526
  "tags": [
9557
- "Plans"
10527
+ "Plan Files"
9558
10528
  ],
9559
- "summary": "Update a plan",
9560
- "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.",
9561
- "operationId": "updateCatalogPlan",
10529
+ "summary": "Update a plan file",
10530
+ "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.",
10531
+ "operationId": "updateCatalogPlanFile",
9562
10532
  "x-mint": {
9563
10533
  "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>"
9564
10534
  },
@@ -9572,22 +10542,25 @@
9572
10542
  "content": {
9573
10543
  "application/json": {
9574
10544
  "schema": {
9575
- "$ref": "#/components/schemas/PlanUpdateRequest"
10545
+ "$ref": "#/components/schemas/PlanFileUpdateRequest"
9576
10546
  }
9577
10547
  }
9578
10548
  }
9579
10549
  },
9580
10550
  "responses": {
9581
10551
  "200": {
9582
- "description": "Updated plan.",
10552
+ "description": "Updated plan file.",
9583
10553
  "content": {
9584
10554
  "application/json": {
9585
10555
  "schema": {
9586
- "$ref": "#/components/schemas/CatalogPlan"
10556
+ "$ref": "#/components/schemas/PlanFile"
9587
10557
  }
9588
10558
  }
9589
10559
  }
9590
10560
  },
10561
+ "404": {
10562
+ "description": "Plan file not found."
10563
+ },
9591
10564
  "401": {
9592
10565
  "description": "Unauthorized \u2014 missing or invalid API key"
9593
10566
  }
@@ -9595,11 +10568,11 @@
9595
10568
  },
9596
10569
  "delete": {
9597
10570
  "tags": [
9598
- "Plans"
10571
+ "Plan Files"
9599
10572
  ],
9600
- "summary": "Archive a plan",
9601
- "description": "Archives all versions of the plan (sets `isArchived=true`).",
9602
- "operationId": "deleteCatalogPlan",
10573
+ "summary": "Delete a plan file",
10574
+ "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.",
10575
+ "operationId": "deleteCatalogPlanFile",
9603
10576
  "x-mint": {
9604
10577
  "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>"
9605
10578
  },
@@ -9610,20 +10583,7 @@
9610
10583
  ],
9611
10584
  "responses": {
9612
10585
  "204": {
9613
- "description": "Plan archived.",
9614
- "content": {
9615
- "application/json": {
9616
- "schema": {
9617
- "$ref": "#/components/schemas/MessageResponse"
9618
- },
9619
- "example": {
9620
- "message": "Plan archived successfully."
9621
- }
9622
- }
9623
- }
9624
- },
9625
- "400": {
9626
- "description": "Already archived."
10586
+ "description": "File deleted."
9627
10587
  },
9628
10588
  "401": {
9629
10589
  "description": "Unauthorized \u2014 missing or invalid API key"
@@ -9631,7 +10591,7 @@
9631
10591
  }
9632
10592
  }
9633
10593
  },
9634
- "/catalog/plans/{identifier}/publish/": {
10594
+ "/catalog/plans/{identifier}/file/{pk}/download/": {
9635
10595
  "parameters": [
9636
10596
  {
9637
10597
  "name": "identifier",
@@ -9642,15 +10602,57 @@
9642
10602
  "schema": {
9643
10603
  "type": "string"
9644
10604
  }
10605
+ },
10606
+ {
10607
+ "name": "pk",
10608
+ "in": "path",
10609
+ "required": true,
10610
+ "description": "Plan file UUID.",
10611
+ "example": "7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0",
10612
+ "schema": {
10613
+ "type": "string",
10614
+ "format": "uuid"
10615
+ }
9645
10616
  }
9646
10617
  ],
10618
+ "get": {
10619
+ "tags": [
10620
+ "Plan Files"
10621
+ ],
10622
+ "summary": "Download a plan file",
10623
+ "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.",
10624
+ "operationId": "downloadCatalogPlanFile",
10625
+ "x-mint": {
10626
+ "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>"
10627
+ },
10628
+ "security": [],
10629
+ "responses": {
10630
+ "302": {
10631
+ "description": "Redirect to the temporary forced-download URL.",
10632
+ "headers": {
10633
+ "Location": {
10634
+ "description": "Signed download URL.",
10635
+ "schema": {
10636
+ "type": "string",
10637
+ "format": "uri"
10638
+ }
10639
+ }
10640
+ }
10641
+ },
10642
+ "404": {
10643
+ "description": "Plan file not found."
10644
+ }
10645
+ }
10646
+ }
10647
+ },
10648
+ "/media/": {
9647
10649
  "post": {
9648
10650
  "tags": [
9649
- "Plans"
10651
+ "Media"
9650
10652
  ],
9651
- "summary": "Publish a plan",
9652
- "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.",
9653
- "operationId": "publishCatalogPlan",
10653
+ "summary": "Generate a presigned upload URL",
10654
+ "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]`).",
10655
+ "operationId": "createPresignedUploadUrl",
9654
10656
  "x-mint": {
9655
10657
  "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>"
9656
10658
  },
@@ -9660,514 +10662,436 @@
9660
10662
  }
9661
10663
  ],
9662
10664
  "requestBody": {
9663
- "required": false,
10665
+ "required": true,
9664
10666
  "content": {
9665
10667
  "application/json": {
9666
10668
  "schema": {
9667
- "$ref": "#/components/schemas/PlanPublishRequest"
10669
+ "$ref": "#/components/schemas/PresignedUploadRequest"
9668
10670
  }
9669
10671
  }
9670
10672
  }
9671
10673
  },
9672
10674
  "responses": {
9673
10675
  "200": {
9674
- "description": "Plan published.",
10676
+ "description": "Presigned upload URL generated.",
9675
10677
  "content": {
9676
10678
  "application/json": {
9677
10679
  "schema": {
9678
- "$ref": "#/components/schemas/PlanPublishResponse"
10680
+ "$ref": "#/components/schemas/PresignedUploadResponse"
9679
10681
  },
9680
10682
  "example": {
9681
- "status": "published"
10683
+ "url": "https://kelviq-uploads.s3.amazonaws.com/",
10684
+ "fields": {
10685
+ "Content-Type": "image/png",
10686
+ "key": "tmp/108713b0-1f81-42cf-a16c-c83b1d4d4148/web-app-manifest-512x512.png",
10687
+ "AWSAccessKeyId": "AKIA...",
10688
+ "policy": "eyJleHBpcmF0aW9uIjogIjIwMjYtMDUtMjFUMTI6MDA6MDBaIiwgImNvbmRpdGlvbnMiOiBbXX0=",
10689
+ "signature": "bWFkZS11cC1zaWduYXR1cmU="
10690
+ },
10691
+ "fileKey": "tmp/108713b0-1f81-42cf-a16c-c83b1d4d4148/web-app-manifest-512x512.png"
9682
10692
  }
9683
10693
  }
9684
10694
  }
9685
10695
  },
9686
10696
  "400": {
9687
- "description": "No price exists, missing currency coverage, or already published."
9688
- },
9689
- "428": {
9690
- "description": "Billing provider not authenticated."
10697
+ "description": "Missing `fileName` or `fileType` in the request body."
9691
10698
  },
9692
10699
  "401": {
9693
10700
  "description": "Unauthorized \u2014 missing or invalid API key"
10701
+ },
10702
+ "500": {
10703
+ "description": "Could not generate upload URL."
9694
10704
  }
9695
10705
  }
9696
10706
  }
9697
10707
  },
9698
- "/catalog/plans/{identifier}/discard/": {
9699
- "parameters": [
9700
- {
9701
- "name": "identifier",
9702
- "in": "path",
9703
- "required": true,
9704
- "description": "Plan identifier.",
9705
- "example": "pro-monthly",
9706
- "schema": {
9707
- "type": "string"
9708
- }
9709
- }
9710
- ],
9711
- "delete": {
10708
+ "/partner/organizations/": {
10709
+ "post": {
9712
10710
  "tags": [
9713
- "Plans"
10711
+ "Partner"
9714
10712
  ],
9715
- "summary": "Discard draft plan",
9716
- "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.",
9717
- "operationId": "discardCatalogPlanDraft",
10713
+ "summary": "Provision an organization",
10714
+ "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.",
10715
+ "operationId": "provisionPartnerOrganization",
9718
10716
  "x-mint": {
9719
10717
  "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>"
9720
10718
  },
9721
10719
  "security": [
9722
10720
  {
9723
- "bearerAuth": []
10721
+ "partnerKeyAuth": []
10722
+ }
10723
+ ],
10724
+ "requestBody": {
10725
+ "required": true,
10726
+ "content": {
10727
+ "application/json": {
10728
+ "schema": {
10729
+ "$ref": "#/components/schemas/PartnerOrganizationProvisionRequest"
10730
+ }
10731
+ }
9724
10732
  }
9725
- ],
10733
+ },
9726
10734
  "responses": {
9727
- "204": {
9728
- "description": "Draft discarded.",
10735
+ "201": {
10736
+ "description": "Organization provisioned.",
9729
10737
  "content": {
9730
10738
  "application/json": {
9731
10739
  "schema": {
9732
- "$ref": "#/components/schemas/MessageResponse"
10740
+ "$ref": "#/components/schemas/PartnerOrganization"
9733
10741
  },
9734
10742
  "example": {
9735
- "message": "Plan discarded successfully."
10743
+ "userId": 4271,
10744
+ "organizationIdentifier": "8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0",
10745
+ "organizationSlug": "acme-corp",
10746
+ "clientKey": "ck_live_a1b2c3d4e5f6",
10747
+ "serverKey": "sk_live_9z8y7x6w5v4u",
10748
+ "partnerExternalId": "acme-corp"
9736
10749
  }
9737
10750
  }
9738
10751
  }
9739
10752
  },
9740
10753
  "400": {
9741
- "description": "Plan is already published; cannot be discarded."
10754
+ "description": "Validation error (e.g. duplicate `externalId` for this partner)."
9742
10755
  },
9743
10756
  "401": {
9744
- "description": "Unauthorized \u2014 missing or invalid API key"
9745
- }
9746
- }
9747
- }
9748
- },
9749
- "/catalog/plans/{identifier}/prices/": {
9750
- "parameters": [
9751
- {
9752
- "name": "identifier",
9753
- "in": "path",
9754
- "required": true,
9755
- "description": "Plan identifier.",
9756
- "example": "pro-monthly",
9757
- "schema": {
9758
- "type": "string"
9759
- }
9760
- },
9761
- {
9762
- "name": "version",
9763
- "in": "query",
9764
- "required": false,
9765
- "description": "Optional plan version to scope the query to.",
9766
- "example": 2,
9767
- "schema": {
9768
- "type": "integer"
10757
+ "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
10758
+ },
10759
+ "409": {
10760
+ "description": "An account with the supplied `email` already exists."
9769
10761
  }
9770
10762
  }
9771
- ],
10763
+ },
9772
10764
  "get": {
9773
10765
  "tags": [
9774
- "Plans"
10766
+ "Partner"
9775
10767
  ],
9776
- "summary": "List plan prices",
9777
- "description": "Returns the prices configured on the plan (one per currency), each with its full per-feature charge configuration.",
9778
- "operationId": "listCatalogPlanPrices",
10768
+ "summary": "List partner organizations",
10769
+ "description": "Returns organizations owned by the authenticated partner. Optionally filter by the partner-side `externalId`.",
10770
+ "operationId": "listPartnerOrganizations",
9779
10771
  "x-mint": {
9780
10772
  "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>"
9781
10773
  },
9782
10774
  "security": [
9783
10775
  {
9784
- "bearerAuth": []
10776
+ "partnerKeyAuth": []
10777
+ }
10778
+ ],
10779
+ "parameters": [
10780
+ {
10781
+ "name": "external_id",
10782
+ "in": "query",
10783
+ "required": false,
10784
+ "description": "If supplied, return only the organization with this partner-side identifier.",
10785
+ "example": "acme-corp",
10786
+ "schema": {
10787
+ "type": "string"
10788
+ }
9785
10789
  }
9786
10790
  ],
9787
10791
  "responses": {
9788
10792
  "200": {
9789
- "description": "Paginated list of plan prices.",
10793
+ "description": "List of organizations.",
9790
10794
  "content": {
9791
10795
  "application/json": {
9792
10796
  "schema": {
9793
- "$ref": "#/components/schemas/PaginatedPlanPrices"
10797
+ "$ref": "#/components/schemas/PartnerOrganizationList"
10798
+ },
10799
+ "example": {
10800
+ "results": [
10801
+ {
10802
+ "userId": 4271,
10803
+ "organizationIdentifier": "8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0",
10804
+ "organizationSlug": "acme-corp",
10805
+ "clientKey": "ck_live_a1b2c3d4e5f6",
10806
+ "serverKey": "sk_live_9z8y7x6w5v4u",
10807
+ "partnerExternalId": "acme-corp"
10808
+ }
10809
+ ],
10810
+ "count": 1
9794
10811
  }
9795
10812
  }
9796
10813
  }
9797
10814
  },
9798
10815
  "401": {
9799
- "description": "Unauthorized \u2014 missing or invalid API key"
10816
+ "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
9800
10817
  }
9801
10818
  }
9802
10819
  }
9803
10820
  },
9804
- "/catalog/plans/{identifier}/prices/bulk/": {
10821
+ "/partner/organizations/{identifier}/": {
9805
10822
  "parameters": [
9806
10823
  {
9807
10824
  "name": "identifier",
9808
10825
  "in": "path",
9809
10826
  "required": true,
9810
- "description": "Plan identifier.",
9811
- "example": "pro-monthly",
10827
+ "description": "Organization UUID identifier (the `organizationIdentifier` from the provision response).",
10828
+ "example": "8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0",
9812
10829
  "schema": {
9813
- "type": "string"
10830
+ "type": "string",
10831
+ "format": "uuid"
9814
10832
  }
9815
10833
  }
9816
10834
  ],
9817
- "post": {
10835
+ "get": {
9818
10836
  "tags": [
9819
- "Plans"
10837
+ "Partner"
9820
10838
  ],
9821
- "summary": "Update plan prices",
9822
- "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.",
9823
- "operationId": "bulkSetCatalogPlanPrices",
10839
+ "summary": "Get a partner organization by identifier",
10840
+ "description": "Retrieve a single organization owned by the authenticated partner, looked up by its kelviq UUID.",
10841
+ "operationId": "retrievePartnerOrganization",
9824
10842
  "x-mint": {
9825
10843
  "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>"
9826
10844
  },
9827
10845
  "security": [
9828
10846
  {
9829
- "bearerAuth": []
10847
+ "partnerKeyAuth": []
9830
10848
  }
9831
10849
  ],
9832
- "requestBody": {
9833
- "required": true,
9834
- "content": {
9835
- "application/json": {
9836
- "schema": {
9837
- "$ref": "#/components/schemas/PlanPriceBulkRequest"
9838
- }
9839
- }
9840
- }
9841
- },
9842
10850
  "responses": {
9843
10851
  "200": {
9844
- "description": "Prices replaced.",
10852
+ "description": "Organization details.",
9845
10853
  "content": {
9846
10854
  "application/json": {
9847
10855
  "schema": {
9848
- "$ref": "#/components/schemas/PlanPriceBulkResponse"
10856
+ "$ref": "#/components/schemas/PartnerOrganization"
9849
10857
  }
9850
10858
  }
9851
10859
  }
9852
10860
  },
9853
- "400": {
9854
- "description": "Validation error (duplicate currencies, invalid price configuration, etc.)."
9855
- },
9856
10861
  "401": {
9857
- "description": "Unauthorized \u2014 missing or invalid API key"
10862
+ "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
10863
+ },
10864
+ "404": {
10865
+ "description": "Organization not found for this partner."
9858
10866
  }
9859
10867
  }
9860
10868
  }
9861
10869
  },
9862
- "/catalog/plans/{identifier}/features/": {
10870
+ "/partner/organizations/by-external-id/{externalId}/": {
9863
10871
  "parameters": [
9864
10872
  {
9865
- "name": "identifier",
10873
+ "name": "externalId",
9866
10874
  "in": "path",
9867
10875
  "required": true,
9868
- "description": "Plan identifier.",
9869
- "example": "pro-monthly",
10876
+ "description": "Partner-side identifier supplied when the organization was provisioned.",
10877
+ "example": "acme-corp",
9870
10878
  "schema": {
9871
10879
  "type": "string"
9872
10880
  }
9873
- },
9874
- {
9875
- "name": "version",
9876
- "in": "query",
9877
- "required": false,
9878
- "description": "Plan version to scope the listing to (GET only).",
9879
- "example": 2,
9880
- "schema": {
9881
- "type": "integer"
9882
- }
9883
10881
  }
9884
10882
  ],
9885
10883
  "get": {
9886
10884
  "tags": [
9887
- "Plan Entitlements"
10885
+ "Partner"
9888
10886
  ],
9889
- "summary": "List plan entitlements",
9890
- "description": "Returns the feature entitlements (with per-entitlement `details`) configured on the plan.",
9891
- "operationId": "listCatalogPlanFeatures",
10887
+ "summary": "Get a partner organization by external ID",
10888
+ "description": "Retrieve a single organization owned by the authenticated partner using the partner-side `externalId`.",
10889
+ "operationId": "retrievePartnerOrganizationByExternalId",
9892
10890
  "x-mint": {
9893
10891
  "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>"
9894
10892
  },
9895
10893
  "security": [
9896
10894
  {
9897
- "bearerAuth": []
10895
+ "partnerKeyAuth": []
9898
10896
  }
9899
10897
  ],
9900
10898
  "responses": {
9901
10899
  "200": {
9902
- "description": "Paginated list of entitlements.",
10900
+ "description": "Organization details.",
9903
10901
  "content": {
9904
10902
  "application/json": {
9905
10903
  "schema": {
9906
- "$ref": "#/components/schemas/PaginatedPlanFeatureEntitlements"
10904
+ "$ref": "#/components/schemas/PartnerOrganization"
9907
10905
  }
9908
10906
  }
9909
10907
  }
9910
10908
  },
9911
10909
  "401": {
9912
- "description": "Unauthorized \u2014 missing or invalid API key"
9913
- }
9914
- }
9915
- },
9916
- "post": {
9917
- "tags": [
9918
- "Plan Entitlements"
9919
- ],
9920
- "summary": "Add plan entitlements",
9921
- "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.",
9922
- "operationId": "addCatalogPlanFeatures",
9923
- "x-mint": {
9924
- "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>"
9925
- },
9926
- "security": [
9927
- {
9928
- "bearerAuth": []
9929
- }
9930
- ],
9931
- "requestBody": {
9932
- "required": true,
9933
- "content": {
9934
- "application/json": {
9935
- "schema": {
9936
- "$ref": "#/components/schemas/PlanFeaturesCreateRequest"
9937
- }
9938
- }
9939
- }
9940
- },
9941
- "responses": {
9942
- "201": {
9943
- "description": "Entitlements added.",
9944
- "content": {
9945
- "application/json": {
9946
- "schema": {
9947
- "$ref": "#/components/schemas/CatalogPlan"
9948
- }
9949
- }
9950
- }
10910
+ "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
9951
10911
  },
9952
- "401": {
9953
- "description": "Unauthorized \u2014 missing or invalid API key"
10912
+ "404": {
10913
+ "description": "Organization not found for this partner."
9954
10914
  }
9955
10915
  }
9956
10916
  }
9957
10917
  },
9958
- "/catalog/plans/{identifier}/features/{feature_id}/": {
9959
- "parameters": [
9960
- {
9961
- "name": "identifier",
9962
- "in": "path",
9963
- "required": true,
9964
- "description": "Plan identifier.",
9965
- "example": "pro-monthly",
9966
- "schema": {
9967
- "type": "string"
9968
- }
9969
- },
9970
- {
9971
- "name": "feature_id",
9972
- "in": "path",
9973
- "required": true,
9974
- "description": "Feature identifier (slug, not UUID).",
9975
- "example": "api-calls",
9976
- "schema": {
9977
- "type": "string"
9978
- }
9979
- }
9980
- ],
9981
- "patch": {
10918
+ "/payment-methods/": {
10919
+ "get": {
9982
10920
  "tags": [
9983
- "Plan Entitlements"
10921
+ "Payment Methods"
9984
10922
  ],
9985
- "summary": "Update plan entitlement",
9986
- "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.",
9987
- "operationId": "updateCatalogPlanFeature",
10923
+ "summary": "List payment methods",
10924
+ "description": "Returns a paginated list of saved payment methods for the authenticated organization, ordered by creation date (newest first). Only payment methods with status `succeeded` are included. Narrow results with `customer_id` and/or `customer_email`.",
10925
+ "operationId": "listPaymentMethods",
9988
10926
  "x-mint": {
9989
10927
  "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>"
9990
10928
  },
9991
- "security": [
10929
+ "parameters": [
10930
+ {
10931
+ "name": "customer_id",
10932
+ "in": "query",
10933
+ "required": false,
10934
+ "description": "Filter to payment methods belonging to the customer with this client-provided `customer_id`.",
10935
+ "schema": {
10936
+ "type": "string"
10937
+ }
10938
+ },
9992
10939
  {
9993
- "bearerAuth": []
9994
- }
9995
- ],
9996
- "requestBody": {
9997
- "required": true,
9998
- "content": {
9999
- "application/json": {
10000
- "schema": {
10001
- "$ref": "#/components/schemas/PlanFeaturePatchRequest"
10002
- }
10940
+ "name": "customer_email",
10941
+ "in": "query",
10942
+ "required": false,
10943
+ "description": "Filter to payment methods belonging to the customer with this email address.",
10944
+ "schema": {
10945
+ "type": "string",
10946
+ "format": "email"
10947
+ }
10948
+ },
10949
+ {
10950
+ "name": "page_size",
10951
+ "in": "query",
10952
+ "required": false,
10953
+ "description": "Number of results per page. Defaults to 10, maximum 100.",
10954
+ "schema": {
10955
+ "type": "integer",
10956
+ "minimum": 1,
10957
+ "maximum": 100
10958
+ }
10959
+ },
10960
+ {
10961
+ "name": "page",
10962
+ "in": "query",
10963
+ "required": false,
10964
+ "description": "Page number to return.",
10965
+ "schema": {
10966
+ "type": "integer",
10967
+ "minimum": 1
10003
10968
  }
10004
10969
  }
10005
- },
10970
+ ],
10006
10971
  "responses": {
10007
10972
  "200": {
10008
- "description": "Entitlement updated.",
10973
+ "description": "A paginated list of payment methods.",
10009
10974
  "content": {
10010
10975
  "application/json": {
10011
- "example": {
10012
- "details": {
10013
- "value": 20000,
10014
- "hasUnlimitedUsage": false
10015
- }
10976
+ "schema": {
10977
+ "$ref": "#/components/schemas/PaymentMethodListResponse"
10016
10978
  }
10017
10979
  }
10018
10980
  }
10019
10981
  },
10020
10982
  "401": {
10021
- "description": "Unauthorized \u2014 missing or invalid API key"
10983
+ "description": "Unauthorized \u2014 missing or invalid API key."
10022
10984
  }
10023
10985
  }
10024
- },
10025
- "delete": {
10986
+ }
10987
+ },
10988
+ "/discount/": {
10989
+ "get": {
10026
10990
  "tags": [
10027
- "Plan Entitlements"
10991
+ "Discounts"
10028
10992
  ],
10029
- "summary": "Delete plan entitlement",
10030
- "description": "Removes the named feature from the plan's entitlements. A new draft version is created if the latest is published.",
10031
- "operationId": "deleteCatalogPlanFeature",
10993
+ "summary": "List discounts",
10994
+ "description": "Returns a paginated list of active, non-archived discounts for the authenticated organization, newest first.",
10995
+ "operationId": "listDiscounts",
10032
10996
  "x-mint": {
10033
10997
  "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>"
10034
10998
  },
10035
- "security": [
10999
+ "parameters": [
10036
11000
  {
10037
- "bearerAuth": []
11001
+ "name": "search",
11002
+ "in": "query",
11003
+ "required": false,
11004
+ "description": "Free-text search across the discount's `name` and `code`.",
11005
+ "schema": {
11006
+ "type": "string"
11007
+ }
11008
+ },
11009
+ {
11010
+ "name": "page_size",
11011
+ "in": "query",
11012
+ "required": false,
11013
+ "description": "Number of results per page. Defaults to 10, maximum 100.",
11014
+ "schema": {
11015
+ "type": "integer",
11016
+ "minimum": 1,
11017
+ "maximum": 100
11018
+ }
11019
+ },
11020
+ {
11021
+ "name": "page",
11022
+ "in": "query",
11023
+ "required": false,
11024
+ "description": "Page number to return.",
11025
+ "schema": {
11026
+ "type": "integer",
11027
+ "minimum": 1
11028
+ }
10038
11029
  }
10039
11030
  ],
10040
11031
  "responses": {
10041
- "204": {
10042
- "description": "Entitlement removed.",
11032
+ "200": {
11033
+ "description": "A paginated list of discounts.",
10043
11034
  "content": {
10044
11035
  "application/json": {
10045
11036
  "schema": {
10046
- "$ref": "#/components/schemas/MessageResponse"
10047
- },
10048
- "example": {
10049
- "message": "Entitlement deleted successfully."
11037
+ "$ref": "#/components/schemas/DiscountListResponse"
10050
11038
  }
10051
11039
  }
10052
11040
  }
10053
11041
  },
10054
11042
  "401": {
10055
- "description": "Unauthorized \u2014 missing or invalid API key"
10056
- }
10057
- }
10058
- }
10059
- },
10060
- "/catalog/plans/{identifier}/file/{pk}/": {
10061
- "parameters": [
10062
- {
10063
- "name": "identifier",
10064
- "in": "path",
10065
- "required": true,
10066
- "description": "Plan identifier.",
10067
- "example": "pro-monthly",
10068
- "schema": {
10069
- "type": "string"
10070
- }
10071
- },
10072
- {
10073
- "name": "pk",
10074
- "in": "path",
10075
- "required": true,
10076
- "description": "Plan file UUID.",
10077
- "example": "7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0",
10078
- "schema": {
10079
- "type": "string",
10080
- "format": "uuid"
11043
+ "description": "Unauthorized \u2014 missing or invalid API key."
10081
11044
  }
10082
11045
  }
10083
- ],
10084
- "patch": {
11046
+ },
11047
+ "post": {
10085
11048
  "tags": [
10086
- "Plan Files"
11049
+ "Discounts"
10087
11050
  ],
10088
- "summary": "Update a plan file",
10089
- "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.",
10090
- "operationId": "updateCatalogPlanFile",
11051
+ "summary": "Create a discount",
11052
+ "description": "Creates a new discount code.",
11053
+ "operationId": "createDiscount",
10091
11054
  "x-mint": {
10092
11055
  "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>"
10093
11056
  },
10094
- "security": [
10095
- {
10096
- "bearerAuth": []
10097
- }
10098
- ],
10099
11057
  "requestBody": {
10100
11058
  "required": true,
10101
11059
  "content": {
10102
11060
  "application/json": {
10103
11061
  "schema": {
10104
- "$ref": "#/components/schemas/PlanFileUpdateRequest"
11062
+ "$ref": "#/components/schemas/DiscountCreateRequest"
10105
11063
  }
10106
11064
  }
10107
11065
  }
10108
11066
  },
10109
11067
  "responses": {
10110
- "200": {
10111
- "description": "Updated plan file.",
11068
+ "201": {
11069
+ "description": "Discount created.",
10112
11070
  "content": {
10113
11071
  "application/json": {
10114
11072
  "schema": {
10115
- "$ref": "#/components/schemas/PlanFile"
11073
+ "$ref": "#/components/schemas/Discount"
10116
11074
  }
10117
11075
  }
10118
11076
  }
10119
11077
  },
10120
- "404": {
10121
- "description": "Plan file not found."
10122
- },
10123
- "401": {
10124
- "description": "Unauthorized \u2014 missing or invalid API key"
10125
- }
10126
- }
10127
- },
10128
- "delete": {
10129
- "tags": [
10130
- "Plan Files"
10131
- ],
10132
- "summary": "Delete a plan file",
10133
- "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.",
10134
- "operationId": "deleteCatalogPlanFile",
10135
- "x-mint": {
10136
- "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>"
10137
- },
10138
- "security": [
10139
- {
10140
- "bearerAuth": []
10141
- }
10142
- ],
10143
- "responses": {
10144
- "204": {
10145
- "description": "File deleted."
11078
+ "400": {
11079
+ "description": "Validation error, or the organization is not enrolled as Merchant of Record."
10146
11080
  },
10147
11081
  "401": {
10148
- "description": "Unauthorized \u2014 missing or invalid API key"
11082
+ "description": "Unauthorized \u2014 missing or invalid API key."
10149
11083
  }
10150
11084
  }
10151
11085
  }
10152
11086
  },
10153
- "/catalog/plans/{identifier}/file/{pk}/download/": {
11087
+ "/discount/{pk}/": {
10154
11088
  "parameters": [
10155
- {
10156
- "name": "identifier",
10157
- "in": "path",
10158
- "required": true,
10159
- "description": "Plan identifier.",
10160
- "example": "pro-monthly",
10161
- "schema": {
10162
- "type": "string"
10163
- }
10164
- },
10165
11089
  {
10166
11090
  "name": "pk",
10167
11091
  "in": "path",
10168
11092
  "required": true,
10169
- "description": "Plan file UUID.",
10170
- "example": "7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0",
11093
+ "description": "Discount UUID.",
11094
+ "example": "b3f1a2c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
10171
11095
  "schema": {
10172
11096
  "type": "string",
10173
11097
  "format": "uuid"
@@ -10176,372 +11100,298 @@
10176
11100
  ],
10177
11101
  "get": {
10178
11102
  "tags": [
10179
- "Plan Files"
10180
- ],
10181
- "summary": "Download a plan file",
10182
- "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.",
10183
- "operationId": "downloadCatalogPlanFile",
10184
- "x-mint": {
10185
- "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>"
10186
- },
10187
- "security": [],
10188
- "responses": {
10189
- "302": {
10190
- "description": "Redirect to the temporary forced-download URL.",
10191
- "headers": {
10192
- "Location": {
10193
- "description": "Signed download URL.",
10194
- "schema": {
10195
- "type": "string",
10196
- "format": "uri"
10197
- }
10198
- }
10199
- }
10200
- },
10201
- "404": {
10202
- "description": "Plan file not found."
10203
- }
10204
- }
10205
- }
10206
- },
10207
- "/media/": {
10208
- "post": {
10209
- "tags": [
10210
- "Media"
11103
+ "Discounts"
10211
11104
  ],
10212
- "summary": "Generate a presigned upload URL",
10213
- "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]`).",
10214
- "operationId": "createPresignedUploadUrl",
11105
+ "summary": "Retrieve a discount",
11106
+ "description": "Fetches a single discount by ID.",
11107
+ "operationId": "retrieveDiscount",
10215
11108
  "x-mint": {
10216
11109
  "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>"
10217
11110
  },
10218
- "security": [
10219
- {
10220
- "bearerAuth": []
10221
- }
10222
- ],
10223
- "requestBody": {
10224
- "required": true,
10225
- "content": {
10226
- "application/json": {
10227
- "schema": {
10228
- "$ref": "#/components/schemas/PresignedUploadRequest"
10229
- }
10230
- }
10231
- }
10232
- },
10233
11111
  "responses": {
10234
11112
  "200": {
10235
- "description": "Presigned upload URL generated.",
11113
+ "description": "Discount details.",
10236
11114
  "content": {
10237
11115
  "application/json": {
10238
11116
  "schema": {
10239
- "$ref": "#/components/schemas/PresignedUploadResponse"
10240
- },
10241
- "example": {
10242
- "url": "https://kelviq-uploads.s3.amazonaws.com/",
10243
- "fields": {
10244
- "Content-Type": "image/png",
10245
- "key": "tmp/108713b0-1f81-42cf-a16c-c83b1d4d4148/web-app-manifest-512x512.png",
10246
- "AWSAccessKeyId": "AKIA...",
10247
- "policy": "eyJleHBpcmF0aW9uIjogIjIwMjYtMDUtMjFUMTI6MDA6MDBaIiwgImNvbmRpdGlvbnMiOiBbXX0=",
10248
- "signature": "bWFkZS11cC1zaWduYXR1cmU="
10249
- },
10250
- "fileKey": "tmp/108713b0-1f81-42cf-a16c-c83b1d4d4148/web-app-manifest-512x512.png"
11117
+ "$ref": "#/components/schemas/Discount"
10251
11118
  }
10252
11119
  }
10253
11120
  }
10254
11121
  },
10255
- "400": {
10256
- "description": "Missing `fileName` or `fileType` in the request body."
10257
- },
10258
- "401": {
10259
- "description": "Unauthorized \u2014 missing or invalid API key"
10260
- },
10261
- "500": {
10262
- "description": "Could not generate upload URL."
11122
+ "404": {
11123
+ "description": "Discount not found."
11124
+ },
11125
+ "401": {
11126
+ "description": "Unauthorized \u2014 missing or invalid API key."
10263
11127
  }
10264
11128
  }
10265
- }
10266
- },
10267
- "/partner/organizations/": {
10268
- "post": {
11129
+ },
11130
+ "patch": {
10269
11131
  "tags": [
10270
- "Partner"
11132
+ "Discounts"
10271
11133
  ],
10272
- "summary": "Provision an organization",
10273
- "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.",
10274
- "operationId": "provisionPartnerOrganization",
11134
+ "summary": "Update a discount",
11135
+ "description": "Toggles a discount on or off. Every other field is immutable after creation.",
11136
+ "operationId": "updateDiscount",
10275
11137
  "x-mint": {
10276
11138
  "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>"
10277
11139
  },
10278
- "security": [
10279
- {
10280
- "partnerKeyAuth": []
10281
- }
10282
- ],
10283
11140
  "requestBody": {
10284
11141
  "required": true,
10285
11142
  "content": {
10286
11143
  "application/json": {
10287
11144
  "schema": {
10288
- "$ref": "#/components/schemas/PartnerOrganizationProvisionRequest"
11145
+ "$ref": "#/components/schemas/DiscountUpdateRequest"
10289
11146
  }
10290
11147
  }
10291
11148
  }
10292
11149
  },
10293
11150
  "responses": {
10294
- "201": {
10295
- "description": "Organization provisioned.",
11151
+ "200": {
11152
+ "description": "Updated discount.",
10296
11153
  "content": {
10297
11154
  "application/json": {
10298
11155
  "schema": {
10299
- "$ref": "#/components/schemas/PartnerOrganization"
10300
- },
10301
- "example": {
10302
- "userId": 4271,
10303
- "organizationIdentifier": "8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0",
10304
- "organizationSlug": "acme-corp",
10305
- "clientKey": "ck_live_a1b2c3d4e5f6",
10306
- "serverKey": "sk_live_9z8y7x6w5v4u",
10307
- "partnerExternalId": "acme-corp"
11156
+ "$ref": "#/components/schemas/Discount"
10308
11157
  }
10309
11158
  }
10310
11159
  }
10311
11160
  },
10312
11161
  "400": {
10313
- "description": "Validation error (e.g. duplicate `externalId` for this partner)."
11162
+ "description": "Validation error."
10314
11163
  },
10315
11164
  "401": {
10316
- "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
10317
- },
10318
- "409": {
10319
- "description": "An account with the supplied `email` already exists."
11165
+ "description": "Unauthorized \u2014 missing or invalid API key."
10320
11166
  }
10321
11167
  }
10322
11168
  },
10323
- "get": {
11169
+ "delete": {
10324
11170
  "tags": [
10325
- "Partner"
11171
+ "Discounts"
10326
11172
  ],
10327
- "summary": "List partner organizations",
10328
- "description": "Returns organizations owned by the authenticated partner. Optionally filter by the partner-side `externalId`.",
10329
- "operationId": "listPartnerOrganizations",
11173
+ "summary": "Delete a discount",
11174
+ "description": "Soft-deletes (archives) the discount. Already-archived discounts return 400.",
11175
+ "operationId": "deleteDiscount",
10330
11176
  "x-mint": {
10331
11177
  "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>"
10332
11178
  },
10333
- "security": [
10334
- {
10335
- "partnerKeyAuth": []
11179
+ "responses": {
11180
+ "204": {
11181
+ "description": "Discount deleted.",
11182
+ "content": {
11183
+ "application/json": {
11184
+ "schema": {
11185
+ "$ref": "#/components/schemas/MessageResponse"
11186
+ },
11187
+ "example": {
11188
+ "message": "Object deleted successfully."
11189
+ }
11190
+ }
11191
+ }
11192
+ },
11193
+ "400": {
11194
+ "description": "This discount is already deleted."
11195
+ },
11196
+ "401": {
11197
+ "description": "Unauthorized \u2014 missing or invalid API key."
10336
11198
  }
11199
+ }
11200
+ }
11201
+ },
11202
+ "/webhook/endpoints/": {
11203
+ "get": {
11204
+ "tags": [
11205
+ "Webhook Endpoints"
10337
11206
  ],
11207
+ "summary": "List webhook endpoints",
11208
+ "description": "Returns a paginated list of webhook endpoints configured for the authenticated organization.",
11209
+ "operationId": "listWebhookEndpoints",
11210
+ "x-mint": {
11211
+ "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
+ },
10338
11213
  "parameters": [
10339
11214
  {
10340
- "name": "external_id",
11215
+ "name": "page_size",
10341
11216
  "in": "query",
10342
11217
  "required": false,
10343
- "description": "If supplied, return only the organization with this partner-side identifier.",
10344
- "example": "acme-corp",
11218
+ "description": "Number of results per page. Defaults to 10, maximum 100.",
10345
11219
  "schema": {
10346
- "type": "string"
11220
+ "type": "integer",
11221
+ "minimum": 1,
11222
+ "maximum": 100
11223
+ }
11224
+ },
11225
+ {
11226
+ "name": "page",
11227
+ "in": "query",
11228
+ "required": false,
11229
+ "description": "Page number to return.",
11230
+ "schema": {
11231
+ "type": "integer",
11232
+ "minimum": 1
10347
11233
  }
10348
11234
  }
10349
11235
  ],
10350
11236
  "responses": {
10351
11237
  "200": {
10352
- "description": "List of organizations.",
11238
+ "description": "A paginated list of webhook endpoints.",
10353
11239
  "content": {
10354
11240
  "application/json": {
10355
11241
  "schema": {
10356
- "$ref": "#/components/schemas/PartnerOrganizationList"
10357
- },
10358
- "example": {
10359
- "results": [
10360
- {
10361
- "userId": 4271,
10362
- "organizationIdentifier": "8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0",
10363
- "organizationSlug": "acme-corp",
10364
- "clientKey": "ck_live_a1b2c3d4e5f6",
10365
- "serverKey": "sk_live_9z8y7x6w5v4u",
10366
- "partnerExternalId": "acme-corp"
10367
- }
10368
- ],
10369
- "count": 1
11242
+ "$ref": "#/components/schemas/WebhookEndpointListResponse"
10370
11243
  }
10371
11244
  }
10372
11245
  }
10373
11246
  },
10374
11247
  "401": {
10375
- "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
10376
- }
10377
- }
10378
- }
10379
- },
10380
- "/partner/organizations/{identifier}/": {
10381
- "parameters": [
10382
- {
10383
- "name": "identifier",
10384
- "in": "path",
10385
- "required": true,
10386
- "description": "Organization UUID identifier (the `organizationIdentifier` from the provision response).",
10387
- "example": "8e1d7b1a-6c4d-4e3a-9b2d-3f6e4c2b1ad0",
10388
- "schema": {
10389
- "type": "string",
10390
- "format": "uuid"
11248
+ "description": "Unauthorized \u2014 missing or invalid API key."
10391
11249
  }
10392
11250
  }
10393
- ],
10394
- "get": {
11251
+ },
11252
+ "post": {
10395
11253
  "tags": [
10396
- "Partner"
11254
+ "Webhook Endpoints"
10397
11255
  ],
10398
- "summary": "Get a partner organization by identifier",
10399
- "description": "Retrieve a single organization owned by the authenticated partner, looked up by its kelviq UUID.",
10400
- "operationId": "retrievePartnerOrganization",
11256
+ "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.",
11258
+ "operationId": "createWebhookEndpoint",
10401
11259
  "x-mint": {
10402
11260
  "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>"
10403
11261
  },
10404
- "security": [
10405
- {
10406
- "partnerKeyAuth": []
11262
+ "requestBody": {
11263
+ "required": true,
11264
+ "content": {
11265
+ "application/json": {
11266
+ "schema": {
11267
+ "$ref": "#/components/schemas/WebhookEndpointCreateRequest"
11268
+ }
11269
+ }
10407
11270
  }
10408
- ],
11271
+ },
10409
11272
  "responses": {
10410
- "200": {
10411
- "description": "Organization details.",
11273
+ "201": {
11274
+ "description": "Webhook endpoint created.",
10412
11275
  "content": {
10413
11276
  "application/json": {
10414
11277
  "schema": {
10415
- "$ref": "#/components/schemas/PartnerOrganization"
11278
+ "$ref": "#/components/schemas/WebhookEndpoint"
10416
11279
  }
10417
11280
  }
10418
11281
  }
10419
11282
  },
10420
- "401": {
10421
- "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
11283
+ "400": {
11284
+ "description": "Validation error \u2014 e.g. an invalid event type, or a URL that resolves to a private/internal address."
10422
11285
  },
10423
- "404": {
10424
- "description": "Organization not found for this partner."
11286
+ "401": {
11287
+ "description": "Unauthorized \u2014 missing or invalid API key."
10425
11288
  }
10426
11289
  }
10427
11290
  }
10428
11291
  },
10429
- "/partner/organizations/by-external-id/{externalId}/": {
11292
+ "/webhook/endpoints/{pk}/": {
10430
11293
  "parameters": [
10431
11294
  {
10432
- "name": "externalId",
11295
+ "name": "pk",
10433
11296
  "in": "path",
10434
11297
  "required": true,
10435
- "description": "Partner-side identifier supplied when the organization was provisioned.",
10436
- "example": "acme-corp",
11298
+ "description": "Webhook endpoint UUID.",
11299
+ "example": "2f6b9e2a-7c1a-4a3e-8b6e-8e6f9a2c1d4a",
10437
11300
  "schema": {
10438
- "type": "string"
11301
+ "type": "string",
11302
+ "format": "uuid"
10439
11303
  }
10440
11304
  }
10441
11305
  ],
10442
11306
  "get": {
10443
11307
  "tags": [
10444
- "Partner"
11308
+ "Webhook Endpoints"
10445
11309
  ],
10446
- "summary": "Get a partner organization by external ID",
10447
- "description": "Retrieve a single organization owned by the authenticated partner using the partner-side `externalId`.",
10448
- "operationId": "retrievePartnerOrganizationByExternalId",
11310
+ "summary": "Retrieve a webhook endpoint",
11311
+ "description": "Fetches a single webhook endpoint by ID.",
11312
+ "operationId": "retrieveWebhookEndpoint",
10449
11313
  "x-mint": {
10450
11314
  "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>"
10451
11315
  },
10452
- "security": [
10453
- {
10454
- "partnerKeyAuth": []
10455
- }
10456
- ],
10457
11316
  "responses": {
10458
11317
  "200": {
10459
- "description": "Organization details.",
11318
+ "description": "Webhook endpoint details.",
10460
11319
  "content": {
10461
11320
  "application/json": {
10462
11321
  "schema": {
10463
- "$ref": "#/components/schemas/PartnerOrganization"
11322
+ "$ref": "#/components/schemas/WebhookEndpoint"
10464
11323
  }
10465
11324
  }
10466
11325
  }
10467
11326
  },
10468
- "401": {
10469
- "description": "Unauthorized \u2014 missing or invalid `X-Kelviq-Partner-Key` header."
10470
- },
10471
11327
  "404": {
10472
- "description": "Organization not found for this partner."
11328
+ "description": "Webhook endpoint not found."
11329
+ },
11330
+ "401": {
11331
+ "description": "Unauthorized \u2014 missing or invalid API key."
10473
11332
  }
10474
11333
  }
10475
- }
10476
- },
10477
- "/payment-methods/": {
10478
- "get": {
11334
+ },
11335
+ "patch": {
10479
11336
  "tags": [
10480
- "Payment Methods"
11337
+ "Webhook Endpoints"
10481
11338
  ],
10482
- "summary": "List payment methods",
10483
- "description": "Returns a paginated list of saved payment methods for the authenticated organization, ordered by creation date (newest first). Only payment methods with status `succeeded` are included. Narrow results with `customer_id` and/or `customer_email`.",
10484
- "operationId": "listPaymentMethods",
11339
+ "summary": "Update a webhook endpoint",
11340
+ "description": "Partially updates a webhook endpoint's URL, event subscriptions, or enabled state.",
11341
+ "operationId": "updateWebhookEndpoint",
10485
11342
  "x-mint": {
10486
11343
  "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>"
10487
11344
  },
10488
- "parameters": [
10489
- {
10490
- "name": "customer_id",
10491
- "in": "query",
10492
- "required": false,
10493
- "description": "Filter to payment methods belonging to the customer with this client-provided `customer_id`.",
10494
- "schema": {
10495
- "type": "string"
10496
- }
10497
- },
10498
- {
10499
- "name": "customer_email",
10500
- "in": "query",
10501
- "required": false,
10502
- "description": "Filter to payment methods belonging to the customer with this email address.",
10503
- "schema": {
10504
- "type": "string",
10505
- "format": "email"
10506
- }
10507
- },
10508
- {
10509
- "name": "page_size",
10510
- "in": "query",
10511
- "required": false,
10512
- "description": "Number of results per page. Defaults to 10, maximum 100.",
10513
- "schema": {
10514
- "type": "integer",
10515
- "minimum": 1,
10516
- "maximum": 100
10517
- }
10518
- },
10519
- {
10520
- "name": "page",
10521
- "in": "query",
10522
- "required": false,
10523
- "description": "Page number to return.",
10524
- "schema": {
10525
- "type": "integer",
10526
- "minimum": 1
11345
+ "requestBody": {
11346
+ "required": true,
11347
+ "content": {
11348
+ "application/json": {
11349
+ "schema": {
11350
+ "$ref": "#/components/schemas/WebhookEndpointUpdateRequest"
11351
+ }
10527
11352
  }
10528
11353
  }
10529
- ],
11354
+ },
10530
11355
  "responses": {
10531
11356
  "200": {
10532
- "description": "A paginated list of payment methods.",
11357
+ "description": "Updated webhook endpoint.",
10533
11358
  "content": {
10534
11359
  "application/json": {
10535
11360
  "schema": {
10536
- "$ref": "#/components/schemas/PaymentMethodListResponse"
11361
+ "$ref": "#/components/schemas/WebhookEndpoint"
10537
11362
  }
10538
11363
  }
10539
11364
  }
10540
11365
  },
11366
+ "400": {
11367
+ "description": "Validation error."
11368
+ },
10541
11369
  "401": {
10542
11370
  "description": "Unauthorized \u2014 missing or invalid API key."
10543
11371
  }
10544
11372
  }
11373
+ },
11374
+ "delete": {
11375
+ "tags": [
11376
+ "Webhook Endpoints"
11377
+ ],
11378
+ "summary": "Delete a webhook endpoint",
11379
+ "description": "Permanently removes the webhook endpoint. It will stop receiving deliveries immediately.",
11380
+ "operationId": "deleteWebhookEndpoint",
11381
+ "x-mint": {
11382
+ "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>"
11383
+ },
11384
+ "responses": {
11385
+ "204": {
11386
+ "description": "Webhook endpoint deleted."
11387
+ },
11388
+ "401": {
11389
+ "description": "Unauthorized \u2014 missing or invalid API key."
11390
+ },
11391
+ "404": {
11392
+ "description": "Webhook endpoint not found."
11393
+ }
11394
+ }
10545
11395
  }
10546
11396
  }
10547
11397
  }