Skip to main content
​
v2.6.0
June 5, 2026

​
New Features

​
Checkout Session — metadata Parameter

checkout.create_session() now accepts an optional metadata parameter for attaching arbitrary key-value pairs to a checkout session. The metadata is returned verbatim on the checkout.completed webhook payload’s metadata field, letting you correlate a completed checkout back to your own records.
response = client.checkout.create_session(
    planIdentifier="plan-pro-monthly",
    chargePeriod="MONTHLY",
    customerId="cust_789",
    successUrl="https://example.com/success",
    metadata={
        "orderId": "order_12345",
        "referralCode": "SUMMER2026",
    },
)
Async variant:
response = await async_client.checkout.create_session(
    planIdentifier="plan-pro-monthly",
    chargePeriod="MONTHLY",
    customerId="cust_789",
    successUrl="https://example.com/success",
    metadata={"orderId": "order_12345"},
)
The keys inside metadata are preserved exactly as provided — they are not transformed on the way to the API, so they survive the round-trip back through webhooks unchanged.
​
v2.5.0
May 10, 2026

​
New Features

​
Subscription Update — trialEnd Parameter

subscriptions.update() now accepts an optional trialEnd parameter to control the trial period when updating a subscription.Pass either:
  • The literal string "now" to end any active trial immediately.
  • An ISO 8601 datetime string (e.g. "2025-12-31 23:59:59") to set a new trial end date. The datetime must be in the future. Naive datetimes are interpreted as UTC.
  • Omit the parameter to preserve the existing trial behavior on the subscription.
# End the trial now
response = client.subscriptions.update(
    subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
    planIdentifier="premium-plan",
    chargePeriod="MONTHLY",
    trialEnd="now",
)

# Extend the trial to a specific future date
response = client.subscriptions.update(
    subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
    planIdentifier="premium-plan",
    chargePeriod="MONTHLY",
    trialEnd="2025-12-31 23:59:59",
)
Async variant:
response = await async_client.subscriptions.update(
    subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
    planIdentifier="premium-plan",
    chargePeriod="MONTHLY",
    trialEnd="2025-12-31 23:59:59",
)
The SDK validates trialEnd client-side — invalid datetime strings or past datetimes raise InvalidRequestError before the request is sent.
​
v2.4.0
May 4, 2026

​
New Features

​
Checkout Session — New Optional Parameters

Three new optional parameters on checkout.create_session() give you more control over the hosted checkout page.discounts_enabled — controls whether the coupon/discount code field is shown. Defaults to True on the server.lock_email — when True, the email field is pre-filled and locked so the customer cannot change it. Defaults to False.default_billing_country — ISO 3166-1 alpha-2 country code (e.g. "US", "GB") used to pre-fill the billing address country field.
response = client.checkout.create_session(
    planIdentifier="plan-pro-monthly",
    chargePeriod="MONTHLY",
    customerId="cust_789",
    successUrl="https://example.com/success",
    discountsEnabled=False,
    lockEmail=True,
    defaultBillingCountry="US",
)
Async variant:
response = await async_client.checkout.create_session(
    planIdentifier="plan-pro-monthly",
    chargePeriod="MONTHLY",
    customerId="cust_789",
    successUrl="https://example.com/success",
    discountsEnabled=False,
    lockEmail=True,
    defaultBillingCountry="US",
)
​
v2.3.0
April 25, 2026

​
New Features

​
Webhook Verification

A new validate_event helper lets you securely verify incoming webhook requests from Kelviq in one step. It validates the HMAC-SHA256 signature using the three headers Kelviq attaches to every webhook delivery, then returns the parsed event dictionary.
from flask import Flask, request
from kelviq_sdk import validate_event, WebhookVerificationError

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    try:
        event = validate_event(
            payload=request.data,
            headers=request.headers,
            secret='<YOUR_WEBHOOK_SECRET>',
        )

        # Process the event
        print('Event type:', event.get('type'))

        return "", 202
    except WebhookVerificationError as e:
        return "", 403
validate_event(payload, headers, secret)
  • payload — Raw request body as bytes or str. Must be the unparsed body — do not pass a pre-parsed dictionary.
  • headers — Any mapping of header name to value (e.g. request.headers in Flask). Header lookup is case-insensitive.
  • secret — Your webhook signing secret (kq_whsec_...) from the Kelviq dashboard.
Returns the parsed event as Dict[str, Any]. Raises WebhookVerificationError if a required header is missing, the signature format is invalid, or the signature does not match.

​
WebhookVerificationError

New exception class raised by validate_event when verification fails. Extends Exception.
​
v2.2.0
April 13, 2026

​
New Features

​
License Management Module

A new client.license module provides full lifecycle management for software licenses. All methods are available in both synchronous and asynchronous clients.license.activate(licenseKey, customerId?, instanceName?, metadata?)Activates a license key and creates a new instance. Returns a LicenseActivateResponse (Pydantic model) containing the instanceId, activatedAt, expiresOn, and the full LicenseDetails object.
response = client.license.activate(
    licenseKey="LIC-XXXX-YYYY-ZZZZ",
    customerId="cust_789",
    instanceName="My MacBook Pro",
    metadata={"os": "macOS", "arch": "arm64"},
)

print(response.instanceId)
print(response.license.activationUsage)       # e.g. 1
print(response.license.plan.product.name)     # e.g. "Kelviq Engine"
print(response.license.subscription.billingType)  # "SUBSCRIPTION"
license.deactivate(licenseKey, instanceId)Deactivates a specific license instance. Returns a LicenseDeactivateResponse with message and deactivatedAt.
response = client.license.deactivate(
    licenseKey="LIC-XXXX-YYYY-ZZZZ",
    instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
)
print(response.message)  # "License instance deactivated successfully."
license.validate(licenseKey, instanceId?)Validates a license key and optionally a specific instance. Returns a LicenseValidateResponse with valid, code, detail, metadata, and the full LicenseDetails.
response = client.license.validate(
    licenseKey="LIC-XXXX-YYYY-ZZZZ",
    instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
)

if response.valid:
    print(f"Valid — code: {response.code}")
else:
    print(f"Invalid — {response.detail}")

​
New Pydantic Models

  • LicenseDetails — Full license object with id, licenseKey, activatedOn, expiresOn, activationUsage, activationLimit, enabled, customer, plan, and subscription.
  • LicenseCustomer — customerId, name, email nested within LicenseDetails.
  • LicensePlan — Expanded with description, version, isLatest, and product (nested LicensePlanProduct model).
  • LicensePlanProduct — id, identifier, name, taxCode, createdOn, modifiedOn.
  • LicenseActivateResponse, LicenseDeactivateResponse, LicenseValidateResponse — Typed Pydantic response models for each operation.

​
SubscriptionData New Fields

Three new fields derived from the subscription’s recurrence string are now included in SubscriptionData (returned within LicenseDetails.subscription and customer subscription summaries):
  • billingType — "SUBSCRIPTION" if the plan has a recurrence, "ONE_TIME" otherwise.
  • recurrenceUnit — Integer unit from the recurrence string (e.g. 1 from "1 month"), or None.
  • recurrenceType — Recurrence period in uppercase (e.g. "MONTH"), or None.
​
v2.1.0
April 2, 2026

​
New Features

​
Customer Portal Module

A new client.portal module lets you create pre-authenticated customer portal sessions server-side and redirect customers directly to their self-serve portal. Available on both synchronous and asynchronous clients.portal.create_session(customerId)
session = client.portal.create_session(customerId="cust_789")

# Redirect your customer — no login required
print(session.customerPortalUrl)
Async variant:
session = await async_client.portal.create_session(customerId="cust_789")
Returns CreatePortalSessionResponse (Pydantic model) with:
  • token (str) — Session token authenticating the portal session.
  • email (str) — The customer’s email address.
  • customerPortalUrl (str) — Pre-authenticated URL to redirect the customer to.
​
v2.0.0
February 27, 2026

​
New Features

​
Entitlements Aggregation Engine

When a customer has multiple active subscriptions, the API can return duplicate featureId entries. The SDK now automatically aggregates them into a single Entitlement model while preserving the raw data.
entitlement = client.entitlements.get_entitlement("cust_123", "email-sends")

# Aggregated values across all subscriptions
print(entitlement.hasAccess)     # True
print(entitlement.usageLimit)    # 1500 (e.g., 1000 from base + 500 from top-up)
print(entitlement.currentUsage)  # 200
print(entitlement.remaining)     # 1300

# Per-subscription details
for item in entitlement.items:
    print(item.usageLimit, item.resetAt)
Aggregation rules:
FieldAggregation Strategy
hasAccessTrue if any raw entry grants access
usageLimitSummed across all entries (for METER feature types)
currentUsageSummed across all entries (for METER feature types)
remainingComputed as usageLimit - currentUsage
hardLimitTrue if any entry has a hard limit
Note: resetAt is intentionally not aggregated at the top level because each subscription item can have a different reset date. Access individual reset dates via entitlement.items[i].resetAt.

​
New Entitlement Pydantic Model

A new model representing an aggregated entitlement:
  • featureId, featureType, hasAccess, hardLimit, usageLimit, currentUsage, remaining
  • items: List[EntitlementDetail] — the raw entries that were aggregated into this model

​
get_entitlements(customerId) — All Entitlements as a Map

Returns a Dict[str, Entitlement] keyed by featureId. Each value is an aggregated model with an .items list containing the original raw entries.
entitlements = client.entitlements.get_entitlements("cust_123")

for feature_id, entitlement in entitlements.items():
    print(f"{feature_id}: hasAccess={entitlement.hasAccess}, remaining={entitlement.remaining}")

​
get_raw_entitlement(customerId, featureId) — Raw API Response for a Feature

Returns the raw API response (CheckEntitlementsResponse) for a specific feature without any aggregation.
raw = client.entitlements.get_raw_entitlement("cust_123", "email-sends")

​
get_raw_entitlements(customerId) — Full Raw API Response

Returns the raw API response for all entitlements without any aggregation.
raw = client.entitlements.get_raw_entitlements("cust_123")

​
Enum Helpers for IDE Autocompletion

New str-based Enum classes:
  • ChargePeriod — ONE_TIME, MONTHLY, YEARLY, WEEKLY, DAILY, THREE_MONTHS, SIX_MONTHS
  • CancellationType — IMMEDIATE, CURRENT_PERIOD_ENDS, SPECIFIC_DATE
from kelviq_sdk import ChargePeriod, CancellationType

response = client.checkout.create_session(
    planIdentifier="pro-plan",
    chargePeriod=ChargePeriod.MONTHLY,
    successUrl="https://example.com/success"
)
Raw string values (e.g., "MONTHLY") continue to work everywhere — fully backward-compatible.

​
Changed

  • get_entitlement(customerId, featureId) now returns Optional[Entitlement] (aggregated) instead of raw CheckEntitlementsResponse. Use get_raw_entitlement() for the original response.
  • get_all_entitlements removed — Use get_entitlements() instead.
  • resetAt removed from top-level Entitlement — Access individual reset dates via the .items list.
​
v1.1.0
February 27, 2026

​
New Features

​
Entitlements Aggregation Engine

When a customer has multiple active subscriptions, the API can return duplicate featureId entries. The SDK now automatically aggregates them into a single Entitlement model while preserving the raw data.
entitlement = client.entitlements.get_entitlement("cust_123", "email-sends")

# Aggregated values across all subscriptions
print(entitlement.has_access)     # True
print(entitlement.usage_limit)    # 1500 (e.g., 1000 from base + 500 from top-up)
print(entitlement.current_usage)  # 200
print(entitlement.remaining)      # 1300

# Per-subscription details
for item in entitlement.items:
    print(item.usage_limit, item.reset_at)
Aggregation rules:
FieldAggregation Strategy
hasAccessTrue if any raw entry grants access
usageLimitSummed across all entries (for METER feature types)
currentUsageSummed across all entries (for METER feature types)
remainingComputed as usageLimit - currentUsage
hardLimitTrue if any entry has a hard limit
Note: resetAt is intentionally not aggregated at the top level because each subscription item can have a different reset date. Access individual reset dates via entitlement.items[i].resetAt.

​
New Entitlement Pydantic Model

A new model representing an aggregated entitlement:
  • featureId, featureType, hasAccess, hardLimit, usageLimit, currentUsage, remaining
  • items: List[EntitlementDetail] — the raw entries that were aggregated into this model

​
get_entitlements(customerId) — All Entitlements as a Map

Returns a Dict[str, Entitlement] keyed by featureId. Each value is an aggregated model with an .items list containing the original raw entries.
entitlements = client.entitlements.get_entitlements("cust_123")

for feature_id, entitlement in entitlements.items():
    print(f"{feature_id}: hasAccess={entitlement.has_access}, remaining={entitlement.remaining}")

​
get_raw_entitlement(customerId, featureId) — Raw API Response for a Feature

Returns the raw API response (CheckEntitlementsResponse) for a specific feature without any aggregation. Includes the customerId wrapper.
raw = client.entitlements.get_raw_entitlement("cust_123", "email-sends")
# CheckEntitlementsResponse with customerId wrapper

​
get_raw_entitlements(customerId) — Full Raw API Response

Returns the raw API response for all entitlements without any aggregation.
raw = client.entitlements.get_raw_entitlements("cust_123")
# CheckEntitlementsResponse with customerId wrapper and all raw entries

​
Enum Helpers for IDE Autocompletion

New str-based Enum classes that improve developer experience with IDE autocompletion and prevent typos:
  • ChargePeriod — ONE_TIME, MONTHLY, YEARLY, WEEKLY, DAILY, THREE_MONTHS, SIX_MONTHS
  • CancellationType — IMMEDIATE, CURRENT_PERIOD_ENDS, SPECIFIC_DATE
from kelviq_sdk import ChargePeriod, CancellationType

# With enums — IDE autocompletion and typo prevention
response = client.checkout.create_session(
    planIdentifier="pro-plan",
    chargePeriod=ChargePeriod.MONTHLY,
    successUrl="https://example.com/success"
)

# Cancel with enum
client.subscriptions.cancel(
    subscriptionId="sub_123",
    cancellationType=CancellationType.CURRENT_PERIOD_ENDS,
)
Raw string values (e.g., "MONTHLY") continue to work everywhere — the enums are fully backward-compatible.

​
Changed

  • get_entitlement(customerId, featureId) now returns Optional[Entitlement] (aggregated) instead of raw CheckEntitlementsResponse. Use get_raw_entitlement() if you need the original response.
  • get_all_entitlements removed — Use get_entitlements() instead, which returns a Dict[str, Entitlement] keyed by featureId.
  • resetAt removed from top-level Entitlement — Access individual reset dates via the .items list.

​
Fixed

  • Removed invalid JavaScript-style comments (// Server-generated UUID) from JSON response blocks in documentation.
  • Fixed // comments to # comments in Python code snippets.
  • Fixed trailing comma in Checkout response JSON block.
  • Fixed typo: “newly created customer” → “updated customer” in customers.update return description.
  • Removed placeholder text from “Supported Functionalities” section.
  • Updated entitlements description to explain multi-subscription aggregation and the items attribute.