Node SDK - Kelviq Documentation

Overview

The Kelviq Node SDK provides a convenient way to interact with the Kelviq REST APIs from your Node application.

Installation

Install the Kelviq SDK using npm or yarn:

npm install @kelviq/node-sdk

yarn add @kelviq/node-sdk

Prerequisites

Before you can initialize the client and use the SDK methods, you need a Server API Key. You can obtain this key from the Kelviq application:

Navigate to Settings.
Go to the API keys section.
Copy the Server API Key.

Security Warning: The Server API Key should never be exposed in client-side code. Use it only in your backend services. For client-side applications, use the Client API Key with the React SDK or JavaScript SDK.

Once copied, add this key to your environment variables (recommended for security):

// Example of setting it in your code (environment variables recommended)
const ACCESS_TOKEN = process.env.KELVIQ_SERVER_API_KEY;

Configuring the Client

The SDK provides a main Kelviq client class. You instantiate it directly with your configuration options.


const ACCESS_TOKEN: string = "YOUR_SECRET_ACCESS_TOKEN";

How to Create a Client

import { Kelviq } from '@kelviq/node-sdk';

const client = new Kelviq({ accessToken: ACCESS_TOKEN });

Caching and offline resilience

Entitlement caching is enabled by default. The SDK keeps a per-process in-memory cache with a 60-second freshness window. Reads follow this order: fresh memory cache, optional distributed cache, then the Entitlement API. A successful API response refreshes both cache levels. If the API is unreachable or returns a server error, the SDK returns the last known cached entitlement response when one exists. If the customer or feature has never been cached, the original request error is thrown.

const client = new Kelviq({
  accessToken: process.env.KELVIQ_SERVER_API_KEY,
  enableCache: true,   // default: true
  cacheTtlMs: 60_000,  // default: 60 seconds
});

Set enableCache: false to disable caching. The in-memory cache and offline reporting queue belong to one Node process and disappear when it restarts. Use the optional Redis store when multiple processes or containers need one shared, durable cache and queue.

npm install ioredis

import { Kelviq, RedisStore } from '@kelviq/node-sdk';

const store = new RedisStore({
  url: process.env.REDIS_URL,
  prefix: 'kelviq:production',
});

const client = new Kelviq({
  accessToken: process.env.KELVIQ_SERVER_API_KEY,
  cacheStore: store,
});

Use the same prefix for every instance that should share state.

Replay queued usage

When a usage or event report fails because of a network problem, the SDK queues it and retries automatically on the next report call. You can also flush the queue explicitly:

const remaining = await client.reporting.flush();

remaining is the number of reports still queued. Without Redis, the queue exists only in the current process. See When the Entitlement API is unavailable for access-control fallback guidance.

Supported Functionalities

The SDK currently supports the following operations:

Customers

The customers module allows you to manage customer records within Kelviq. You can access these operations via the customers attribute on an initialized Kelviq client instance.

Creates a new customer

const newCustomer = await client.customers.create({
    customerId: "unique-customer-id-789",
    email: "new.node.customer@example.com",
    name: "Node SDK User",
    metadata: { source: "sdk_import", priority: "high" }
});

Response

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "customerId": "unique-customer-id-789",
  "name": "Node SDK User",
  "email": "new.node.customer@example.com",
  "details": {},
  "metadata": {
    "source": "sdk_import",
    "priority": "high"
  },
  "createdOn": "2025-06-04T06:03:30.195790Z",
  "modifiedOn": "2025-06-04T06:03:30.195831Z"
}

Required Parameters:

customerId : A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.

Optional Parameters:

email : The email address of the customer. Must be a valid email format.
name : The name of the customer.
metadata : An object of custom key-value pairs to store additional information about the customer.

Returns: An instance of CustomerResponse (TypeScript Interface), representing the newly created customer record. Key attributes include:

id : The server-generated unique UUID for the customer record.
customerId : The client-provided customer identifier.
name : The customer’s name.
email : The customer’s email.
details : Any server-added details about the customer (typically read-only).
metadata : The metadata associated with the customer.
createdOn : ISO 8601 timestamp of when the customer was created.
modifiedOn : ISO 8601 timestamp of when the customer was last modified.

Updates an existing customer

This operation performs a partial update (PATCH), so you only need to provide the fields you want to change.

const updatedCustomer = await client.customers.update({
  customerId: "unique-customer-id-789",
  name: "Node SDK User (Updated)",
  metadata: { tier: "premium_plus" }
});

Response

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "customerId": "unique-customer-id-789",
  "name": "Node SDK User (Updated)",
  "email": "new.node.customer@example.com",
  "details": {},
  "metadata": {
    "tier": "premium_plus"
  },
  "createdOn": "2025-06-04T06:03:30.195790Z",
  "modifiedOn": "2025-06-04T06:03:30.195831Z"
}

Parameters: Required Parameters:

customerId : A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.

Optional Parameters:

email : The email address of the customer. Must be a valid email format.
name : The name of the customer.
metadata : An object of custom key-value pairs to store additional information about the customer.

Returns: An instance of CustomerResponse (TypeScript Interface), representing the updated customer record. Key attributes include:

id : The server-generated unique UUID for the customer record.
customerId : The client-provided customer identifier.
name : The customer’s name.
email : The customer’s email.
details : Any server-added details about the customer (typically read-only).
metadata : The metadata associated with the customer.
createdOn : ISO 8601 timestamp of when the customer was created.
modifiedOn : ISO 8601 timestamp of when the customer was last modified.

Checkout

The checkout module provides functionalities for creating and managing checkout sessions. You can access these operations via the checkout attribute on an initialized Kelviq client instance. This operation creates a new checkout session for a customer, allowing them to proceed with a purchase or subscription.

import { Kelviq, CHARGE_PERIOD_CHOICES } from '@kelviq/node-sdk';

const response = await client.checkout.createSession({
  planIdentifier: "plan-pro-monthly",
  chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
  successUrl: "https://yourwebsite.com/checkout/success",
  customerId: "cust_789",  // Recommended, otherwise it will create a new customer
  trialPeriod: 14,
});

Response

 {
      "checkoutUrl": "https://www.kelviq.com/checkout/cs_fBhCIBerpe1pAsRW6P4wYc8WHqMdfdr457hd3oOLjhAFx/",
      "checkoutSessionId": "cs_test_b1sNi7D6u9iMCUFV1UZi9ZwerfaiXKdOOmr3DCUW6XdCZIr5Id1F7G"
  }

Required Parameters:

planIdentifier : The identifier of the specific plan the customer is checking out with. planIdentifier is mandatory.
successUrl : The URL to which the user will be redirected after a successful checkout.
chargePeriod : The billing cycle for the subscription. Must be one of:
- "ONE_TIME"
- "MONTHLY"
- "YEARLY"
- "WEEKLY"
- "DAILY"
- "TWENTY_EIGHT_DAYS"
- "THREE_MONTHS"
- "SIX_MONTHS"

Optional Parameters:

offeringId : The ID (uuid) of the offering the customer is checking out with.
pricingTableId : The id (uuid) of the pricing table being used for this checkout. (Considered only if offeringId is not provided)
ruleId : The id (uuid) of the pricing rule being applied. (Considered only if offeringId is not provided)
customerId : The ID of the customer initiating the checkout. (If not provided, a new customer will be created)
features: A list of objects, where each object represents a feature and its desired quantity. Each object must have two keys:
- "identifier" : The unique identifier for the feature.
- "quantity": The desired quantity for this feature.
  - Example: [{"identifier": "seats", "quantity": 10}, {"identifier": "api-calls-tier1", "quantity": 5000}]
ipAddress : The IP Address of the customer, used for location based pricing.
trialPeriod : Number of trial days to apply. Must be an integer greater than or equal to 1 and overrides the selected plan’s configured trial period.
currencyCode : The currency code for the checkout session (e.g. "USD"). Required when customAmount is provided.
customAmount : A custom amount to charge for this checkout session. When provided, taxBehavior and currencyCode are also required.
taxBehavior : Specifies how taxes are applied to the customAmount. Required when customAmount is provided. Must be one of:
- "INCLUSIVE" — Tax is included in the custom amount.
- "EXCLUSIVE" — Tax is added on top of the custom amount.
discountsEnabled : Whether the discount/coupon code field is shown on the checkout page. Defaults to true.
lockEmail : When true, the email field is pre-filled and locked so the customer cannot change it. Defaults to false.
defaultBillingCountry : ISO 3166-1 alpha-2 country code (e.g. "US", "GB") used to pre-fill the billing address country on the checkout page.
metadata : An object of arbitrary key-value pairs to attach to the checkout session. The keys are preserved exactly as supplied and the object is returned unchanged on the checkout.completed webhook’s metadata field. Example: { "order_ref": "ABC-123", "source": "pricing_page" }.

Returns: An instance of CreateCheckoutSessionResponse (Object), which includes:

checkoutSessionId : The unique ID for the created checkout session.
checkoutUrl : The URL that the customer should be redirected to in order to complete the payment and activate the subscription/purchase.

Entitlements

The entitlements module allows you to check and retrieve customer entitlements for various features. These operations target a specific edge API endpoint ( https://edge.api.kelviq.com by default) and use the GET HTTP method with query parameters.

Checks if a specific customer has access to a particular feature.

This method directly returns a boolean indicating access status.

const hasAccess = await client.entitlements.hasAccess({
      customerId: "cust_node_ent_123",
      featureId: "premium-reporting-node"
    });

Response

 true

Required Parameters:

customerId : The unique identifier for the customer.
featureId : The unique identifier for the feature whose access is being checked.

Returns:

boolean: true if the customer has access to the specified feature (considering feature type, limits, etc.), false otherwise or if the feature is not found in their entitlements.

Retrieves the aggregated entitlement for a specific feature for a given customer.

const entitlement = await client.entitlements.getEntitlement({
    customerId: "cust_node_ent_123",
    featureId: "premium-reporting-node"
});

Response

 {
      "featureId": "advanced-analytics",
      "featureType": "METER",
      "hasAccess": true,
      "hardLimit": false,
      "usageLimit": 3,
      "currentUsage": 0,
      "remaining": 3,
      "items": [
          {
              "featureId": "advanced-analytics",
              "featureType": "METER",
              "hasAccess": true,
              "resetAt": "2025-05-22 08:27:45",
              "hardLimit": false,
              "usageLimit": 3,
              "currentUsage": 0,
              "remaining": 3
          }
      ]
 }

Required Parameters:

customerId : The unique identifier for the customer.
featureId : The unique identifier for the feature whose access is being checked.

Returns: An aggregated Entitlement object, or null if the feature is not found. If the customer has multiple subscriptions, there can be multiple raw entries for the same featureId. The SDK aggregates them and keeps raw entries in the items array. Note: resetAt is only available on individual items (not at the top level) because it can differ across subscriptions. The structure includes:

featureId: string
hasAccess: boolean — For METER features, computed as remaining === null || remaining > 0. For BOOLEAN and CUSTOMIZABLE features, true if at least one item grants access.
featureType: string — "METER", "BOOLEAN", or "CUSTOMIZABLE".
hardLimit: boolean | null — For METER, true if any item has a hard limit. For BOOLEAN, always false.
usageLimit: number | null — For METER, summed across all items. For CUSTOMIZABLE, taken from the first item. For BOOLEAN, always null.
currentUsage: number | null — For METER, summed across all items. For CUSTOMIZABLE, taken from the first item. For BOOLEAN, always 0.
remaining: number | null — For METER, computed as usageLimit - currentUsage. For CUSTOMIZABLE, taken from the first item. For BOOLEAN, always null.
items (EntitlementDetail[]): An array containing all raw entitlement entries for this featureId. Each item includes resetAt.

Retrieves all aggregated entitlements for a given customer.

const entitlements = await client.entitlements.getEntitlements({
    customerId: "cust_node_ent_123"
});

// Access a specific feature directly by featureId
const analytics = entitlements["advanced-analytics"];

Response

 {
      "advanced-analytics": {
          "featureId": "advanced-analytics",
          "featureType": "METER",
          "hasAccess": true,
          "hardLimit": false,
          "usageLimit": 3,
          "currentUsage": 0,
          "remaining": 3,
          "items": [
              {
                  "featureId": "advanced-analytics",
                  "featureType": "METER",
                  "hasAccess": true,
                  "resetAt": "2025-05-22 08:27:45",
                  "hardLimit": false,
                  "usageLimit": 3,
                  "currentUsage": 0,
                  "remaining": 3
              }
          ]
      }
 }

Required Parameters:

customerId : The unique identifier for the customer.

Returns: A Record<string, Entitlement> keyed by featureId. If the customer has multiple subscriptions, there can be multiple raw entries for the same featureId. The SDK aggregates them and keeps raw entries in the items array. Note: resetAt is only available on individual items (not at the top level) because it can differ across subscriptions. Each Entitlement value has the same structure as described in getEntitlement above.

Retrieves the raw entitlement from the API for a specific feature.

const response = await client.entitlements.getRawEntitlement({
    customerId: "cust_node_ent_123",
    featureId: "premium-reporting-node"
});

Response

 {
      "customerId": "cust_456",
      "entitlements": [
          {
              "featureId": "advanced-analytics",
              "featureType": "METER",
              "hasAccess": true,
              "resetAt": "2025-05-22 08:27:45",
              "hardLimit": false,
              "usageLimit": 3,
              "currentUsage": 0,
              "remaining": 3
          }
      ]
 }

Required Parameters:

customerId : The unique identifier for the customer.
featureId : The unique identifier for the feature.

Returns: An instance of CheckEntitlementsResponse (Object). This returns the raw API response without aggregation. The structure includes:

customerId : The customer’s ID.
entitlements (EntitlementDetail[]): A list containing raw entitlement details. Each EntitlementDetail has fields like:
- featureId: string
- hasAccess: boolean
- featureType: string
- resetAt: string
- hardLimit: boolean | null
- usageLimit: number | null
- currentUsage: number | null
- remaining: number | null

Retrieves all raw entitlements from the API without aggregation.

const response = await client.entitlements.getRawEntitlements({
    customerId: "cust_node_ent_123"
});

Response

 {
      "customerId": "cust_456",
      "entitlements": [
          {
              "featureId": "advanced-analytics",
              "featureType": "METER",
              "hasAccess": true,
              "resetAt": "2025-05-22 08:27:45",
              "hardLimit": false,
              "usageLimit": 3,
              "currentUsage": 0,
              "remaining": 3
          }
      ]
 }

Required Parameters:

customerId : The unique identifier for the customer.

Returns: An instance of CheckEntitlementsResponse (Object). This returns the raw API response without aggregation. The structure includes:

customerId : The customer’s ID.
entitlements (EntitlementDetail[]): A list containing raw entitlement details. Each EntitlementDetail has fields like:
- featureId: string
- hasAccess: boolean
- featureType: string
- resetAt: string
- hardLimit: boolean | null
- usageLimit: number | null
- currentUsage: number | null
- remaining: number | null

Reporting

Reporting pre-aggregated usages for customer

This endpoint is used for reporting the pre-aggregated feature usage from your application (client-level) to the Kelviq application. It allows you to update the usage count for a specific feature associated with a customer.

import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';

const response = await client.reporting.reportUsage({
    value: 150,
    customerId: "customer_001",
    featureId: "seats",
    behaviour: BEHAVIOUR_CHOICES.SET
});

Response

 {
      "value": 150,
      "customerId": "customer_001",
      "featureId": "seats",
      "behaviour": "SET",
      "orgId": "1",
      "eventName": "aggregated.usage",
      "idempotencyKey": "597ee95063c744ed9bcc9b1cf5676a8a",
      "timestamp": "2025-05-22 08:27:45.430732"
  }

Required Parameters:

value: The usage value being reported.
customerId : The unique identifier for the customer associated with this usage.
featureId : The unique identifier for the feature for which usage is being reported.
behaviour parameter dictates how the usage is updated:
- SET: This will replace the current usage value for the feature with the new value provided.
- DELTA: This will increment the existing usage value for the feature by the amount specified in the value parameter

Returns: An instance of ReportUsageResponse (Object), which includes:

value: The usage value that was recorded.
customerId : The customer ID associated with the usage.
featureId : The feature Identifier for which usage was recorded.
behaviour : The behaviour type (“SET” or “DELTA”) that was processed.
orgId : The organization ID associated with this record, as determined by the server.
eventName : An internal event name generated by the server for this usage report (e.g., “aggregated.usage”).
idempotencyKey : A unique idempotency key generated by the server for this specific usage report instance.
timestamp : The server-generated UTC timestamp (string format) indicating when the usage report was processed.

Subscriptions

The subscriptions module allows you to list, retrieve, create, preview updates, update, and cancel customer subscriptions. You can access these operations via the subscriptions attribute on an initialized Kelviq client instance.

List subscriptions

Retrieves a paginated list of subscriptions for a customer.

const page = await client.subscriptions.list({
  customerId: "cust_789",
  page: 1,
  pageSize: 20,
});

for (const subscription of page.results) {
  console.log(subscription.id, subscription.status);
}

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
      "startDate": "2025-07-28",
      "endDate": null,
      "status": "active",
      "trialDaysRemaining": 0,
      "customerId": "cust_789",
      "billingType": "SUBSCRIPTION",
      "files": [],
      "links": [],
      "license": []
    }
  ]
}

Required Parameters:

customerId (string): The client-defined identifier of the customer whose subscriptions will be returned.

Optional Parameters:

page (number): Page number to retrieve.
pageSize (number): Number of subscriptions to return per page.
modifiedOnAfter (string): Only return subscriptions modified on or after this ISO 8601 timestamp.
modifiedOnBefore (string): Only return subscriptions modified on or before this ISO 8601 timestamp.

Returns: A PaginatedSubscriptionResponse containing count, next, previous, and a results array of SubscriptionData objects.

Retrieve a subscription

Retrieves one subscription using its Kelviq subscription ID.

const subscription = await client.subscriptions.retrieve({
  subscriptionId: "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
});

console.log(subscription.id, subscription.status);
subscription.files?.forEach((file) => console.log(file.name, file.downloadUrl));
subscription.links?.forEach((link) => console.log(link.name, link.url));
subscription.license?.forEach((license) =>
  console.log(license.licenseKey, license.activationLimit),
);

Response

{
  "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
  "externalSubscriptionId": "sub_1RpoZoSBstCzyocS7iPmith3",
  "startDate": "2025-07-28",
  "endDate": null,
  "billingPeriodStartTime": "2025-07-28T10:46:34Z",
  "billingPeriodEndTime": "2025-08-28T10:46:34Z",
  "amount": "261.00",
  "recurrence": "month",
  "currency": "usd",
  "status": "active",
  "trialDaysRemaining": 0,
  "customerId": "cust_789",
  "billingType": "SUBSCRIPTION",
  "recurrenceUnit": 1,
  "recurrenceType": "MONTH",
  "files": [],
  "links": [],
  "license": []
}

Required Parameters:

subscriptionId (string): The Kelviq UUID of the subscription.

Returns: A SubscriptionData object. A missing subscription throws NotFoundError.

Create a subscription

Creates a subscription directly for a customer without requiring a checkout session.

import { CHARGE_PERIOD_CHOICES } from '@kelviq/node-sdk';

const subscription = await client.subscriptions.create({
  planIdentifier: "plan-pro-monthly",
  chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
  customerId: "cust_789",
  successUrl: "https://example.com/subscription/success",
  features: [{ identifier: "seats", quantity: 5 }],
  ipAddress: "103.154.35.20",
});

console.log(subscription.id, subscription.status);

Required Parameters:

planIdentifier (string): Identifier of the plan to subscribe to.
chargePeriod (ChargePeriod): By default, organizations can use MONTHLY, THREE_MONTHS, SIX_MONTHS, YEARLY, and ONE_TIME. To enable DAILY, WEEKLY, or TWENTY_EIGHT_DAYS, contact hi@kelviq.com.
customerId (string): Client-defined identifier of the customer.

Optional Parameters:

successUrl (string): URL to redirect to after successful subscription creation.
features (FeatureListItem[]): Feature identifiers and requested quantities.
ipAddress (string): Customer IP address used for location-based pricing.

Returns: A CreateSubscriptionResponse containing the created subscription, including its plan files, links, and issued licenses when available.

Updates an existing subscription to a new plan

import { CHARGE_PERIOD_CHOICES, PAYMENT_BEHAVIORS, PRORATION_BEHAVIORS } from '@kelviq/node-sdk';

try {
    const response = await client.subscriptions.update({
      subscriptionId: "sub_node_78058918",
      planIdentifier: "premium-plan-node",
      chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
      prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
      trialEnd: "2027-12-31T23:59:59Z", // or "now" to end the trial immediately
      paymentBehavior: PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT
    });
} catch (e) {
    console.error(`Error updating subscription: ${e}`);
}

Response

 {
    "subscriptionId": "dffaf07e-4517-47db-ba3a-59a05aa2d465"
 }

Required Parameters:

subscriptionId : The unique identifier of the subscription to be updated.
planIdentifier : The identifier of the new plan.
chargePeriod : The new charging period for the subscription. Must be one of:
- "ONE_TIME"
- "MONTHLY"
- "YEARLY"
- "WEEKLY"
- "DAILY"
- "TWENTY_EIGHT_DAYS"
- "THREE_MONTHS"
- "SIX_MONTHS"

Optional Parameters:

offeringId : The ID of the new offering, if applicable.
pricingTableId : The ID of the new pricing table, if applicable.
ruleId : The ID of the new pricing rule, if applicable.
ipAddress : The IP Address of the customer, used for location based pricing.
features: An array of objects, where each object represents a feature and its desired quantity to update for the subscription. Each object must have two keys:
- "identifier" : The unique identifier for the feature.
- "quantity" : The desired quantity for this feature.
  - Example: [{"identifier": "seats", "quantity": 10}, {"identifier": "projects", "quantity": 5}]
trialEnd (string): Controls the trial period for the updated subscription. Accepts either:
- The literal string "now" to end any active trial immediately.
- An ISO 8601 datetime string (e.g. "2027-12-31T23:59:59Z") to set a new trial end date. The datetime must be in the future. Naive datetimes (no timezone designator) are interpreted as UTC.
- If omitted, the existing trial behavior on the subscription is preserved.
paymentBehavior (PaymentBehavior): Set to PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT (the value "activate_on_payment") to keep the current subscription active while payment is pending. The new plan and features are applied only after payment succeeds. If the pending update expires, the current subscription remains unchanged. Omit this field to use the default immediate-update behavior.
prorationBehavior (ProrationBehavior): Controls how a mid-period change is billed. Use PRORATION_BEHAVIORS.IMMEDIATE_CHARGE, PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE, or PRORATION_BEHAVIORS.NO_PRORATION. When omitted, the organization’s default is used.

The SDK validates trialEnd client-side — invalid datetime strings or past datetimes throw InvalidRequestError before the request is sent. Returns: An instance of UpdateSubscriptionResponse, which includes:

subscriptionId (string): UUID of the updated subscription.

Preview a subscription update

Calculates the financial effect of an update without changing the subscription, creating an invoice, or charging the customer.

import { CHARGE_PERIOD_CHOICES, PRORATION_BEHAVIORS } from '@kelviq/node-sdk';

const preview = await client.subscriptions.previewUpdate({
  subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
  planIdentifier: "premium-plan",
  chargePeriod: CHARGE_PERIOD_CHOICES.YEARLY,
  prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
  features: [{ identifier: "seats", quantity: 10 }],
});

console.log(preview.recurringAmount, preview.amountChargedImmediately);
console.log(preview.nextInvoice?.lineItems);

Required parameters are subscriptionId, planIdentifier, and chargePeriod. Optional parameters are prorationBehavior, features, ipAddress, and trialEnd. Returns: A SubscriptionUpdatePreviewResponse with recurring and immediate amounts in major and minor units, plus an optional next invoice and its line items.

Cancel an active subscription for a customer.

import { CANCELLATION_TYPES } from '@kelviq/node-sdk';

try {
    const response = await client.subscriptions.cancel({
        subscriptionId: "sub_node_78058918",
        cancellationType: CANCELLATION_TYPES.CURRENT_PERIOD_ENDS
    });
} catch (e) {
    console.error(`Error cancelling subscription: ${e}`);
}

Response

 {
    "message": "Subscription cancellation processed successfully."
 }

Required Parameters:

subscriptionId : The unique identifier of the subscription to be cancelled.
cancellationType : The type of cancellation to perform. Must be one of:
- "IMMEDIATE": The subscription is cancelled immediately.
- "CURRENT_PERIOD_ENDS": The subscription will remain active until the end of the current billing period and then cancel.
- "SPECIFIC_DATE": The subscription will be cancelled on the specified cancellationDate.
cancellationDate : The specific date for cancellation if cancellationType is "SPECIFIC_DATE". Must be in YYYY-MM-DD format. This parameter is required if cancellationType is "SPECIFIC_DATE".

Returns: An instance of CancelSubscriptionResponse, which includes:

message : A confirmation message indicating the result of the cancellation request.

Charges

The charges module immediately charges a customer’s saved payment method for a one-time plan. Use sandbox mode when testing this operation.

const charge = await client.charges.create({
  planIdentifier: "lifetime-access",
  chargePeriod: "ONE_TIME",
  customerId: "cust_789",
  currencyCode: "USD",
  customAmount: 49.99,
  taxBehavior: "INCLUSIVE",
  features: [{ identifier: "seats", quantity: 5 }],
});

console.log(charge.id, charge.status, charge.amount);

planIdentifier, chargePeriod: "ONE_TIME", and customerId are required. customAmount must be positive and requires currencyCode. taxBehavior accepts INCLUSIVE or EXCLUSIVE and defaults to EXCLUSIVE on the API. Optional fields also include features and ipAddress. Returns: A CreateChargeResponse containing the charge record, amount, currency, status, product, plan, features, and customer details.

Refunds

The refunds module allows you to list, create, and retrieve refunds for orders owned by your organization. You can access these operations via the refunds attribute on an initialized Kelviq client instance.

List refunds

const page = await client.refunds.list({
  status: "SUCCEEDED",
  startDate: "2026-07-01",
  page: 1,
  pageSize: 10,
});

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
      "reason": "REQUESTED_BY_CUSTOMER",
      "amountUnits": 2500,
      "amount": 25,
      "internalNote": "Customer requested a partial refund.",
      "failureReason": null,
      "status": "SUCCEEDED",
      "order": { "id": "ORD-20260715123000-A1B2C" }
    }
  ]
}

Optional Parameters:

search : Search by refund ID, order ID, customer name, email, or ID.
status : Filter by refund status. One of "PENDING", "PROCESSING", "SUCCEEDED", "FAILED", "CANCELED".
startDate : Include refunds created on or after this date (YYYY-MM-DD).
endDate : Include refunds created on or before this date (YYYY-MM-DD).
page : Page number to return.
pageSize : Number of results per page. Defaults to 10, maximum 100.

Returns: A RefundListResponse (TypeScript Interface) with count, next, previous, and results: RefundResponse[].

Create a refund

const refund = await client.refunds.create({
  orderId: "ORD-20260715123000-A1B2C",
  amountUnits: 2500,
  reason: "REQUESTED_BY_CUSTOMER",
  internalNote: "Customer requested a partial refund.",
});

Response

{
  "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
  "reason": "REQUESTED_BY_CUSTOMER",
  "amountUnits": 2500,
  "amount": 25,
  "internalNote": "Customer requested a partial refund.",
  "failureReason": null,
  "status": "SUCCEEDED",
  "order": { "id": "ORD-20260715123000-A1B2C" }
}

Required Parameters:

orderId : The ID of an order owned by your organization.

Optional Parameters:

amountUnits : Amount to refund in the currency’s minor unit (e.g. cents for USD). Takes precedence over amount when both are provided.
amount : Amount to refund in the currency’s major unit (e.g. dollars for USD). Used only when amountUnits is omitted.
reason : One of "DUPLICATE", "FRAUDULENT", "REQUESTED_BY_CUSTOMER", "OTHER". Defaults to "REQUESTED_BY_CUSTOMER".
internalNote : An internal note associated with the refund.

Omit both amountUnits and amount to refund the order’s entire remaining refundable balance. The amount must be positive and cannot exceed the order’s remaining refundable balance — the SDK throws InvalidRequestError if orderId is missing, and the API rejects invalid amounts. Returns: A RefundResponse (TypeScript Interface) with id, reason, amountUnits, amount, internalNote, failureReason, status, and the complete serialized order.

Retrieve a refund

const refund = await client.refunds.retrieve({
  refundId: "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
});

Required Parameters:

refundId : The UUID of the refund.

Returns: A RefundResponse (TypeScript Interface), as above.

Payment Methods

The paymentMethods module lists saved payment methods for your organization. You can access this operation via the paymentMethods attribute on an initialized Kelviq client instance.

List payment methods

const page = await client.paymentMethods.list({
  customerId: "geo-jacob",
  pageSize: 10,
});

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 482,
      "customer": {
        "customerId": "geo-jacob",
        "name": "Geo Jacob",
        "email": "geojacob@example.com",
        "billingAddress": { "country": "US" }
      },
      "methodType": "card",
      "methodData": {
        "brand": "visa",
        "last4": "4242",
        "expMonth": 12,
        "expYear": 2029,
        "funding": "credit",
        "country": "US"
      },
      "isDefault": true,
      "status": "succeeded",
      "createdOn": "2026-04-02T06:12:04.123456Z",
      "modifiedOn": "2026-04-02T06:12:04.123456Z"
    }
  ]
}

Optional Parameters:

customerId : Filter to payment methods belonging to the customer with this client-provided customerId.
customerEmail : Filter to payment methods belonging to the customer with this email address.
page : Page number to return.
pageSize : Number of results per page. Defaults to 10, maximum 100.

Only payment methods with status "succeeded" are included in results. Returns: A PaymentMethodListResponse (TypeScript Interface) with count, next, previous, and results: PaymentMethodResponse[]. Each methodData object is payment-provider-specific; for card it includes brand, last4, expMonth, expYear, funding, and country.

Transactions

The transactions module lists financial transactions for your organization, ordered newest first. You can access this operation via the transactions attribute on an initialized Kelviq client instance.

List transactions

const page = await client.transactions.list({
  status: "success",
  startDate: "2026-07-01",
  page: 1,
  pageSize: 25,
});

console.log(page.results[0].amountTotal, page.results[0].morFeeBreakdown);

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "5b274952-0e54-48f6-aec6-e8a3f202b12e",
      "order": { "id": "ORD-20260715123000-A1B2C" },
      "createdOn": "2026-07-28T10:30:00Z",
      "currency": "USD",
      "currencySymbol": "$",
      "amountTotal": 100,
      "morFee": 4,
      "morFeeBreakdown": [
        { "name": "fixed_fee", "percentage": null, "valueUnits": 40, "currency": "USD" },
        { "name": "base_fee", "percentage": "2.9", "valueUnits": 290, "currency": "USD" },
        { "name": "subscription_fee", "percentage": "0.7", "valueUnits": 70, "currency": "USD" }
      ],
      "collectedTax": 0,
      "netPayout": 96,
      "status": "success",
      "transactionType": "CHARGE",
      "paymentMethodType": "card",
      "availableOn": "2026-08-04",
      "isSettled": false,
      "paymentMethodName": "visa",
      "last4": "4242"
    }
  ]
}

Optional Parameters:

search : Search by payment-provider IDs, customer name, email or ID, product name, or payment method type.
status : Filter by transaction status. One of "success", "failure", "pending".
startDate : Include transactions created on or after this date (YYYY-MM-DD).
endDate : Include transactions created on or before this date (YYYY-MM-DD).
page : Page number to return.
pageSize : Number of results per page. Defaults to 10, maximum 100.

Returns: A TransactionListResponse (TypeScript Interface) with count, next, previous, and results: TransactionResponse[]. Each transaction includes an itemized morFeeBreakdown (Merchant of Record fee components) when applicable — empty when no such fee applies.

License

The license module allows you to activate, deactivate, and validate software licenses. You can access these operations via the license attribute on an initialized Kelviq client instance.

Activate a license key

Creates a new license instance for a given license key, optionally associating it with a customer.

const response = await client.license.activate({
    licenseKey: "LIC-XXXX-YYYY-ZZZZ",
    customerId: "cust_789",
    instanceName: "My MacBook Pro",
    metadata: { os: "macOS", arch: "arm64" }
});

console.log(response.instanceId);

Response

{
  "instanceId": "8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
  "activatedAt": "2026-01-27T10:33:00Z",
  "expiresOn": "2027-01-27T10:33:00Z",
  "license": {
    "id": "7be7a5b6-7a0e-4178-a085-8ef48f0649ab",
    "licenseKey": "LIC-A8D5F89E-B46B-472C-9BED-66EE2545B85E",
    "activatedOn": "2026-01-22T03:26:56Z",
    "expiresOn": "2026-01-23T03:26:56Z",
    "activationUsage": 1,
    "activationLimit": 4,
    "enabled": true,
    "customer": {
      "customerId": "cfa95cf8c8d24e8b9d3d2d1ada98a94d",
      "name": "Geo",
      "email": "geo@kelviq.com"
    },
    "plan": {
      "identifier": "pro-yearly",
      "name": "Pro Yearly",
      "description": "Pro plan billed yearly",
      "product": {
        "id": "d970ab2d-834f-4c52-8742-2e6ed7e8a31f",
        "identifier": "kelviq-engine",
        "name": "Kelviq Engine",
        "taxCode": "software",
        "createdOn": "2025-01-01T00:00:00Z",
        "modifiedOn": "2025-06-01T00:00:00Z"
      },
      "version": 1,
      "isLatest": true
    },
    "subscription": {
      "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
      "recurrence": "1 month",
      "billingPeriodStartTime": "2026-01-22T03:26:56Z",
      "billingPeriodEndTime": "2026-02-22T03:26:56Z",
      "startDate": "2026-01-22",
      "endDate": null,
      "status": "active",
      "amount": "49.00",
      "currency": "usd",
      "trialDaysRemaining": 0,
      "billingType": "SUBSCRIPTION",
      "recurrenceUnit": 1,
      "recurrenceType": "MONTH"
    }
  }
}

Required Parameters:

licenseKey : The license key string to activate.

Optional Parameters:

customerId : The ID of the customer this instance is associated with.
instanceName : A human-readable name for this instance (e.g. device name).
metadata : An object of custom key-value pairs to attach to the instance.

Returns: An instance of LicenseActivateResponse, which includes:

instanceId (string): The unique ID of the newly created license instance.
activatedAt (string): ISO 8601 timestamp of when the instance was activated.
expiresOn (string | null): ISO 8601 timestamp of when the instance expires, if applicable.
license (LicenseDetails): The full license object. Key fields:
- id : Server-generated UUID for the license.
- licenseKey : The license key string.
- activatedOn (string | null): ISO 8601 timestamp of when the license was first activated.
- expiresOn (string | null): ISO 8601 timestamp of when the license expires.
- activationUsage : Number of currently active instances.
- activationLimit : Maximum number of allowed concurrent activations.
- enabled : Whether the license is active.
- customer (object | null): The associated customer, if any. Fields: customerId, name, email.
- plan (object | null): The plan associated with this license, if any. Fields: identifier, name, description, version, isLatest, and product (object with id, identifier, name, taxCode, createdOn, modifiedOn).
- subscription (object | null): Subscription details, if any. Fields: id, recurrence, billingPeriodStartTime, billingPeriodEndTime, startDate, endDate, status, amount, currency, trialDaysRemaining, billingType, recurrenceUnit, recurrenceType.

Deactivate a license instance

Deactivates a specific license instance by its instance ID.

try {
    const response = await client.license.deactivate({
        licenseKey: "LIC-XXXX-YYYY-ZZZZ",
        instanceId: "8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5a6b"
    });
    console.log(response.message);
} catch (e) {
    console.error(`Error deactivating license: ${e}`);
}

Response

{
  "message": "License instance deactivated successfully.",
  "deactivatedAt": "2026-01-27T10:35:00Z"
}

Required Parameters:

licenseKey : The license key string.
instanceId : The unique ID of the instance to deactivate.

Returns: An instance of LicenseDeactivateResponse, which includes:

message (string): Confirmation message.
deactivatedAt (string): ISO 8601 timestamp of when the instance was deactivated.

Validate a license key

Checks whether a license key (and optionally a specific instance) is valid.

const response = await client.license.validate({
    licenseKey: "LIC-XXXX-YYYY-ZZZZ",
    instanceId: "8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5a6b"  // optional
});

if (response.valid) {
    console.log("License is valid:", response.code);
} else {
    console.log("License invalid:", response.detail);
}

Response

{
  "valid": true,
  "code": "VALID",
  "detail": "Instance ID valid for this license.",
  "metadata": {
    "os": "macOS",
    "arch": "arm64"
  },
  "license": {
    "id": "7be7a5b6-7a0e-4178-a085-8ef48f0649ab",
    "licenseKey": "LIC-A8D5F89E-B46B-472C-9BED-66EE2545B85E",
    "activatedOn": "2026-01-22T03:26:56Z",
    "expiresOn": "2026-01-23T03:26:56Z",
    "activationUsage": 1,
    "activationLimit": 4,
    "enabled": true,
    "customer": {
      "customerId": "cfa95cf8c8d24e8b9d3d2d1ada98a94d",
      "name": "Geo",
      "email": "geo@kelviq.com"
    },
    "plan": {
      "identifier": "pro-yearly",
      "name": "Pro Yearly",
      "product": {
        "id": "d970ab2d-834f-4c52-8742-2e6ed7e8a31f",
        "identifier": "kelviq-engine",
        "name": "Kelviq Engine",
        "taxCode": "software"
      }
    },
    "subscription": {
      "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
      "recurrence": "1 month",
      "billingPeriodStartTime": "2026-01-22T03:26:56Z",
      "billingPeriodEndTime": "2026-02-22T03:26:56Z",
      "startDate": "2026-01-22",
      "endDate": null,
      "status": "active",
      "amount": "49.00",
      "currency": "usd",
      "trialDaysRemaining": 0,
      "billingType": "SUBSCRIPTION",
      "recurrenceUnit": 1,
      "recurrenceType": "MONTH"
    }
  }
}

Required Parameters:

licenseKey : The license key string to validate.

Optional Parameters:

instanceId : If provided, also validates that this specific instance is active for the given license key.

Returns: An instance of LicenseValidateResponse, which includes:

valid (boolean): Whether the license (and instance, if provided) is valid.
code (string): A short status code (e.g. "VALID", "INVALID", "EXPIRED").
detail (string): A human-readable description of the validation result.
metadata (object | null): Any metadata attached to the instance, if applicable.
license (LicenseDetails | null): The full license object (same structure as in activate), or null if not found.

Portal

The portal module allows you to create authenticated customer portal sessions. Once a session is created, you can redirect your customer directly to their self-serve customer portal without requiring them to log in manually. You can access these operations via the portal attribute on an initialized Kelviq client instance.

Creates a new customer portal session

const session = await client.portal.createSession({
    customerId: "cust_789",
});

// Build the signed portal link — customerPortalUrl alone does not
// authenticate; the token must be appended as a query parameter.
const portalLink = `${session.customerPortalUrl}?token=${session.token}`;

// Redirect your customer to the portal
res.redirect(portalLink);

Response

{
  "token": "cpt-4f7c5dc4-da9f-447b-d447-6206d835ed6d:23fca530-ajeb-4685-b3d5-9918h6d38275",
  "email": "geo@example.com",
  "customerPortalUrl": "https://www.kelviq.com/portal/paritydeals/"
}

Required Parameters:

customerId : The unique identifier of the customer for whom the portal session is being created.

Returns: An instance of CreatePortalSessionResponse (TypeScript Interface), which includes:

token : The session token that authenticates the customer portal session.
email : The email address of the customer.
customerPortalUrl : The customer’s billing portal base URL. This URL alone does not authenticate the session — append the token as a query parameter (${customerPortalUrl}?token=${token}) to produce the signed link you share with the customer. The token expires, so create a fresh session per visit.

Deep-linking to add a payment method

You can send a customer directly to the add payment method form and have them redirected back to your application when they’re done. Append these query parameters to the signed portal link, targeting the billing page:

Parameter	Required	Description
`intent`	Yes	Set to `add_payment_method` to auto-open the add payment method form.
`returnUrl`	No	URL-encoded `https` URL of your application. After the payment method is saved, the customer is redirected here with `?kelviq_setup=success` appended. `http` is only allowed for `localhost` during development.
`customerId`	No	Opens the form for this specific customer account. If omitted, the customer’s first account is used.

const session = await client.portal.createSession({
    customerId: "cust_789",
});

const returnUrl = encodeURIComponent("https://your-app.com/billing/done");
const addPaymentMethodLink =
    `${session.customerPortalUrl}billing` +
    `?token=${session.token}` +
    `&intent=add_payment_method` +
    `&customerId=cust_789` +
    `&returnUrl=${returnUrl}`;

res.redirect(addPaymentMethodLink);

After the customer saves their payment method, the portal redirects them to https://your-app.com/billing/done?kelviq_setup=success.

Webhooks

Kelviq can send real-time webhook notifications to your server when events occur in your account — for example, when a subscription is created or an invoice is paid.

Verifying webhook signatures

Every webhook request includes three headers that you must use to verify the request is genuinely from Kelviq:

Header	Description
`webhook-id`	Unique identifier for the event
`webhook-timestamp`	Unix timestamp of when the event was sent
`webhook-signature`	HMAC-SHA256 signature, prefixed with `v1,`

Use the validateEvent helper to verify the signature and parse the event in one step. It throws WebhookVerificationError if the signature is invalid.

import { validateEvent, WebhookVerificationError } from '@kelviq/node-sdk';
import express from 'express';

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = validateEvent(
      req.body,
      req.headers,
      '<YOUR_WEBHOOK_SECRET>',
    );

    // Process the event
    console.log('Event type:', event.type);

    res.sendStatus(202);
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      return res.sendStatus(403);
    }
    throw err;
  }
});

Use express.raw() (not express.json()) so that the raw request body is preserved for signature verification. Parsing the body as JSON before verification will break the signature check.

On a framework built on the Fetch API — Next.js route handlers, Hono, Remix, SvelteKit, Cloudflare Workers — request.headers is a Headers object, not a plain object. Convert it with Object.fromEntries, and read the body with request.text() so it stays unparsed:

import { validateEvent, WebhookVerificationError } from '@kelviq/node-sdk';

export async function POST(request: Request) {
  const body = await request.text();

  try {
    const event = validateEvent(
      body,
      Object.fromEntries(request.headers),
      process.env.KELVIQ_WEBHOOK_SECRET!,
    );

    console.log('Event type:', event.type);

    return new Response(null, { status: 202 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      return new Response(null, { status: 403 });
    }
    throw err;
  }
}

Passing a Headers object straight to validateEvent fails with Missing required webhook headers, because the helper reads headers as plain object entries.

Webhook event types

See Webhook event types for the complete list of supported events and their descriptions.

Best practices

Return quickly — respond with a 2xx status before doing any heavy processing. Kelviq retries up to 3 times at 60-second intervals if it does not receive a 2xx.
Use idempotency — use the webhook-id header (or the event id field) to detect and skip duplicate deliveries.
Validate every request — always verify the signature before trusting the payload.

Using the Sandbox Environment

For testing and development, you can configure the client to use the sandbox environment. This ensures that no production data is affected. To do this, set the environment option to ‘sandbox’ during client initialization.

import { Kelviq } from '@kelviq/node-sdk';

const client = new Kelviq({
  accessToken: 'YOUR_SANDBOX_ACCESS_TOKEN',
  environment: 'sandbox'
});

To pick the environment from the KELVIQ_ENV variable that the Kelviq CLI and MCP server also read, use environmentFromEnv(): it returns 'sandbox' when KELVIQ_ENV is unset or empty, 'production' or 'sandbox' when it is set to one of those, and throws on any other value.

import { Kelviq, environmentFromEnv } from '@kelviq/node-sdk';

const client = new Kelviq({
  accessToken: process.env.KELVIQ_SERVER_API_KEY!,
  environment: environmentFromEnv(), // reads KELVIQ_ENV: sandbox when unset
});

The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.

​Overview

​Installation

​Prerequisites

​Configuring the Client

​How to Create a Client

​Caching and offline resilience

​Share the cache across instances

​Replay queued usage

​Supported Functionalities

​Customers

​Creates a new customer

​Updates an existing customer

​Checkout

​Entitlements

​Checks if a specific customer has access to a particular feature.

​Retrieves the aggregated entitlement for a specific feature for a given customer.

​Retrieves all aggregated entitlements for a given customer.

​Retrieves the raw entitlement from the API for a specific feature.

​Retrieves all raw entitlements from the API without aggregation.

​Reporting

​Reporting pre-aggregated usages for customer

​Subscriptions

​List subscriptions

​Retrieve a subscription

​Create a subscription

​Updates an existing subscription to a new plan

​Preview a subscription update

​Cancel an active subscription for a customer.

​Charges

​Refunds

​List refunds

​Create a refund

​Retrieve a refund

​Payment Methods

​List payment methods

​Transactions

​List transactions

​License

​Activate a license key

​Deactivate a license instance

​Validate a license key

​Portal

​Creates a new customer portal session

​Deep-linking to add a payment method

​Webhooks

​Verifying webhook signatures

​Webhook event types

​Best practices

​Using the Sandbox Environment

Overview

Installation

Prerequisites

Configuring the Client

How to Create a Client

Caching and offline resilience

Share the cache across instances

Replay queued usage

Supported Functionalities

Customers

Creates a new customer

Updates an existing customer

Checkout

Entitlements

Checks if a specific customer has access to a particular feature.

Retrieves the aggregated entitlement for a specific feature for a given customer.

Retrieves all aggregated entitlements for a given customer.

Retrieves the raw entitlement from the API for a specific feature.

Retrieves all raw entitlements from the API without aggregation.

Reporting

Reporting pre-aggregated usages for customer

Subscriptions

List subscriptions

Retrieve a subscription

Create a subscription

Updates an existing subscription to a new plan

Preview a subscription update

Cancel an active subscription for a customer.

Charges

Refunds

List refunds

Create a refund

Retrieve a refund

Payment Methods

List payment methods

Transactions

List transactions

License

Activate a license key

Deactivate a license instance

Validate a license key

Portal

Creates a new customer portal session

Deep-linking to add a payment method

Webhooks

Verifying webhook signatures

Webhook event types

Best practices

Using the Sandbox Environment