Node SDK

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 Developers 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 });

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
});

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"
- "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.

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 manage customer subscriptions, including updates and cancellation. You can access these operations via the subscriptions attribute on an initialized Kelviq client instance.

Updates an existing subscription to a new plan

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

try {
    const response = await client.subscriptions.update({
      subscriptionId: "sub_node_78058918",
      planIdentifier: "premium-plan-node",
      chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY
    });
} 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"
- "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}]

Returns: An instance of UpdateSubscriptionResponse, which includes:

subscriptionId (string): UUID of the updated subscription.

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.

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'
});

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.

Backend Integration

Frontend Integration

Promotions UI

Overview

Installation

Prerequisites

Configuring the Client

How to Create a Client

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

Updates an existing subscription to a new plan

Cancel an active subscription for a customer.

Using the Sandbox Environment

Backend Integration

Frontend Integration

Promotions UI

​Overview

​Installation

​Prerequisites

​Configuring the Client

​How to Create a Client

​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

​Updates an existing subscription to a new plan

​Cancel an active subscription for a customer.

​Using the Sandbox Environment

Overview

Installation

Prerequisites

Configuring the Client

How to Create a Client

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

Updates an existing subscription to a new plan

Cancel an active subscription for a customer.

Using the Sandbox Environment