API

Changelog for the Kelviq API

​

v1.3.1

July 21, 2026

New Features

Activate Subscription Updates After Payment

POST /subscriptions/{subscriptionId}/update/ now accepts the optional paymentBehavior field. Set it to activate_on_payment to keep the customer’s current subscription active while payment for the change is pending.

{
  "planIdentifier": "premium-plan",
  "chargePeriod": "MONTHLY",
  "paymentBehavior": "activate_on_payment"
}

The new plan, billing period, and feature changes are applied only after payment succeeds. If the pending update expires before payment is completed, the current subscription remains unchanged. Omitting paymentBehavior preserves the existing immediate-update behavior.

​

v1.3.0

July 16, 2026

New Features

List, Create, and Retrieve Refunds

The Refunds API now supports the complete refund workflow:

• GET /refunds/ — List refunds: Returns a paginated list of refunds for the authenticated organization, with search, status, date-range, and pagination filters.
• POST /refunds/ — Create a refund: Creates a full or partial refund for an order. Provide amountUnits or amount for a partial refund, or omit both to refund the remaining balance.
• GET /refunds/{refundId}/ — Retrieve a refund: Returns a refund by its Kelviq UUID.

Create requests use orderId to identify the order. List results, newly created refunds, and retrieved refunds share the same response format, including the refund amount, reason, status, failure details, internal note, and associated order.

​

v1.2.0

July 14, 2026

New Features

Subscription List, Create, and Retrieve APIs

The Subscriptions API now includes three new endpoints for reading and creating subscriptions:

• GET /subscriptions/ — List subscriptions: Retrieves a paginated list for a customer. The customer_id query parameter is required.
• POST /subscriptions/create/ — Create a subscription: Creates a subscription directly for a customer without requiring a checkout session.
• GET /subscriptions/{subscriptionId}/ — Retrieve a subscription: Retrieves a subscription by its Kelviq UUID.

Subscription list, create, and retrieve responses now include:

• files — downloadable files attached to the subscription’s plan.
• links — external links attached to the plan.
• license — issued licenses associated with the subscription.

One-Time Charges

The new POST /charges/ endpoint immediately charges a customer’s saved payment method without creating a checkout session. The chargePeriod must be ONE_TIME.

​

v1.1.0

May 7, 2026

New Features

Enhanced Checkout Configuration

You can now pass additional configuration parameters when creating a checkout session via the API. These new fields allow for tighter control over the customer experience:

• lockEmail: When set to true, the email address field on the checkout page is disabled, preventing customers from changing the email associated with the session.
• discountsEnabled: A boolean to explicitly allow or disallow discount code application on the checkout page.
• defaultBillingCountry: Pre-fills the billing country field (e.g., "IN").

Example Payload:

{
  "planIdentifier": "base",
  "successUrl": "[https://kelviq.com/checkout/success](https://kelviq.com/checkout/success)",
  "chargePeriod": "MONTHLY",
  "customerId": "sachin",
  "lockEmail": true,
  "discountsEnabled": false,
  "defaultBillingCountry": "IN"
}

​

v1.0.0

May 7, 2026

New Features

Custom Dynamic Amount Support

Added support for custom dynamic amounts on the checkout page. You can now pass a specific custom_amount directly via the checkout API, which is ideal for usage-based, variable, or custom-quoted pricing models.

• custom_amount: The specific numeric amount to be charged to the customer. This overrides static plan pricing and is ideal for usage-based, variable, or custom-quoted pricing models.

• tax_behavior: Specifies how taxes should be applied to the custom amount. For example, setting it to “INCLUSIVE” means the tax is already factored into the custom_amount, while “EXCLUSIVE” would add the tax on top of the base amount.

• currency_code: The three-letter ISO currency code (e.g., “INR”, “USD”) that defines the currency in which the custom_amount should be processed.

{
  "planIdentifier": "automatic-pricing",
  "successUrl": "[https://www.kelviq.com/](https://www.kelviq.com/)",
  "chargePeriod": "MONTHLY",
  "customerId": "sam-altman0010",
  "custom_amount": 1200,
  "tax_behavior": "INCLUSIVE",
  "currency_code": "INR"
}