Unavailable
} > {({ formattedPrice, isFree, hasFreeTrial, trialPeriod }) => (
{formattedPrice}
{hasFreeTrial && Try free for {trialPeriod} days}
)}
```
The render prop receives:
| Field | Type | Description |
| - | - | - |
| `plan` | `RawPricingPlan` | Full plan object |
| `charge` | `RawPricingCharge \| null` | Charge for the requested billing period |
| `amount` | `number` | Raw numeric amount |
| `formattedPrice` | `string` | Localized price string (e.g. `$9.99`) or `"Free"` |
| `currencySymbol` | `string` | e.g. `$` |
| `currencyCode` | `string` | e.g. `USD` |
| `pricingLocale` | `string` | e.g. `en-US` |
| `isFree` | `boolean` | `true` when `priceType === 'FREE'` |
| `hasFreeTrial` | `boolean` | Whether a free trial is available |
| `trialPeriod` | `number` | Trial length in days |
##### `No features available
} > {({ feature, plan, index }) => (- ` | Comma-separated event types — see the [event list](/guides/webhooks#event-types). Required. |
| `--write-secret
- {ent.featureId}: {ent.hasAccess ? 'Enabled' : 'Disabled'} ({ent.featureType}) ))}
- {sub.plan.name} — {sub.status} ({sub.recurrence}) ))}
- {plan.displayName} — {plan.price.priceType} ))}
- {ent.featureId}: {ent.hasAccess ? 'Enabled' : 'Disabled'} ({ent.featureType}) ))}
` | What customers enter at checkout: uppercase letters and digits. Required. |
| `--percent ` | Percentage off, 1–100. Exactly one of `--percent` or `--amount`. |
| `--amount ` | Fixed amount off in normal currency units; needs `--currency`. |
| `--currency ` | ISO currency code for `--amount`. |
| `--duration ` | How long the discount applies. Default `once`. |
| `--months ` | With `--duration repeating`: how many **billing periods** it applies for. Not calendar months — `3` on a yearly plan is three years, so scope a "first 3 months" code to monthly plans. |
| `--product ` | Limit the code to one product, by identifier or UUID. The CLI resolves the identifier to the UUID the API wants. |
| `--plans ` | With `--product`: comma-separated plan identifiers. Omit to cover every plan of the product. |
| `--max-redemptions ` | Total number of uses across all customers. |
| `--redeem-by ` | ISO 8601 date/time after which the code stops working. |
| `--prod` / `--yes` / `--json` | As for `webhook add`. |
Discount codes need a Merchant of Record organization.
### kelviq discount list
Lists codes with amount, duration and state. `--search ` filters by name or code; `--prod` and `--json` as above.
# Environments & authentication
Source: https://docs.kelviq.com/cli/environments
How the CLI targets sandbox vs. production, where keys live, and how to authenticate in CI.
Every Kelviq organization has a **sandbox** environment alongside production — see the [sandbox guide](/guides/sandbox). The CLI is sandbox-first: every command targets sandbox unless you explicitly pass `--prod`.
```shell theme={null}
kelviq pull # sandbox
kelviq pull --prod # production
kelviq push --prod # production, after a diff + confirmation
```
There is deliberately no configuration that makes an unqualified command touch production — `--prod` is always explicit, per command. The one command that inherently targets production, `kelviq promote`, says so in its name, shows you the full diff of what production would change, and requires confirmation before writing (plus a typed production confirmation before any `--prune` archive). Promote needs **both** keys configured: sandbox to read, production to write.
Each environment has its own API host and its own keys — the CLI selects both together:
| Environment | API host | Key |
| - | - | - |
| Sandbox (default) | `https://sandboxapi.kelviq.com/api/v1` | Sandbox Server API Key |
| Production (`--prod`) | `https://api.kelviq.com/api/v1` | Production Server API Key |
Always pair the key with its own environment's host — a key from one environment doesn't belong on the other's host, and the CLI never mixes them.
***
## Getting keys
The CLI authenticates with **Server API Keys** from the dashboard:
1. Sign in at [app.kelviq.com](https://app.kelviq.com).
2. Go to **Settings → [API keys](https://app.kelviq.com/settings/api-keys)**.
3. Copy the Server API Key for the environment you want (sandbox and production have separate keys).
> [!WARNING]
>
> Server API Keys have full API access. Never expose them in client-side code, commit them to version control, or paste them into shared chats. The CLI never echoes or logs a key.
***
## Key storage
`kelviq login` stores keys in a per-user config file:
```text theme={null}
~/.config/kelviq/config.json
```
* The file is created with owner-only permissions (`0600`), inside a `0700` directory.
* `XDG_CONFIG_HOME` is respected if set (the file lives at `$XDG_CONFIG_HOME/kelviq/config.json`).
* Sandbox and production keys are stored as separate entries; `kelviq logout` removes them individually (`--prod`) or together (`--all`).
***
## Environment variables
Environment variables **override** the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys. They can come from the shell or from the project's env file: before every command, the CLI reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory, never overriding a variable the shell already sets. Pass `--env-file ` to read a specific file instead, or `--no-env-file` to read none. `kelviq env` lists the files it read. `KELVIQ_SERVER_API_KEY` and `KELVIQ_ENV` work the same way as in the [MCP server](/guides/mcp-server); the environment-named keys are CLI-only.
| Variable | Purpose |
| - | - |
| `KELVIQ_SERVER_API_KEY` | Server key for the environment named by `KELVIQ_ENV`. |
| `KELVIQ_ENV` | `sandbox` (the default when unset, as in the MCP server) or `production`. |
| `KELVIQ_SANDBOX_SERVER_API_KEY` | Server key that always applies to sandbox. |
| `KELVIQ_PRODUCTION_SERVER_API_KEY` | Server key that always applies to production. |
| `KELVIQ_BASE_URL`, `KELVIQ_EDGE_URL` | Override the API or edge URL for the `KELVIQ_ENV` environment. You almost never need these. |
* A variable named for an environment wins over `KELVIQ_SERVER_API_KEY`. Use `KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` when one shell needs both keys, for example for `kelviq promote`.
* `KELVIQ_ENV` only decides which environment `KELVIQ_SERVER_API_KEY` belongs to. It never makes a command target production — only `--prod` does.
* Any value other than `sandbox` or `production` makes commands fail rather than guess.
A typical CI setup skips `kelviq login` entirely:
```yaml theme={null}
# e.g. GitHub Actions
env:
KELVIQ_SERVER_API_KEY: ${{ secrets.KELVIQ_SANDBOX_SERVER_API_KEY }}
KELVIQ_ENV: sandbox
```
```shell theme={null}
kelviq pull --force # authenticates from the environment variables
```
For `kelviq promote` in CI, set both `KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` instead.
If a command needs a key and finds none — neither in the environment nor stored — it fails with a message naming the variables to set and where to get a key. If `KELVIQ_SERVER_API_KEY` is set for the other environment, the message says so.
***
## Checking your setup
`kelviq env` prints the full picture without calling the API, and `kelviq env --check` adds one authenticated read per configured key:
```text theme={null}
Environment : sandbox (default — use --prod to target production)
KELVIQ_ENV : unset (sandbox) — unprefixed KELVIQ_* vars apply to sandbox
Sandbox URL : https://sandboxapi.kelviq.com/api/v1
Prod URL : https://api.kelviq.com/api/v1
Sandbox key : set
Prod key : missing
Org : unknown — Kelviq has no key-introspection endpoint yet
```
> [!NOTE]
>
> `set` means a key is configured (stored, from an env file, or from the shell) — not that it's valid. `kelviq env --check` verifies each key with one read against its own environment and exits non-zero if any configured key is rejected. Kelviq has no key-introspection endpoint yet, so the CLI can't display your organization name.
# kelviq.config.ts reference
Source: https://docs.kelviq.com/cli/kelviq-config
The pricing-as-code file format: builders, fields, and the rules that keep it portable.
`kelviq.config.ts` is a plain TypeScript file that declares your pricing catalog. You author it by hand (starting from `kelviq init`) or generate it from a live environment with `kelviq pull` — the two are interchangeable starting points.
The format follows one design idea: the file describes the **desired state** of your catalog, and nothing else. Anything that's an artifact of a particular deployment — UUIDs, draft/published status, server-generated timestamps — stays out, which is what makes the same file portable across sandbox and production and meaningful to diff over time. It's TypeScript rather than YAML or JSON for one reason: **types**. Your editor autocompletes every field, invalid enums fail to compile, and a config that type-checks is a config the CLI can read.
A config file imports three **builders** from `@kelviq/cli/config` and exports the results:
```ts theme={null}
import { product, feature, plan } from '@kelviq/cli/config';
export const app = product({
identifier: 'my-app',
name: 'My App',
taxCode: 'saas',
});
export const apiCalls = feature({
identifier: 'api-calls',
name: 'API calls',
type: 'METER',
featureDetails: {
featureSubType: 'PRE_AGGREGATED_USAGE',
units: { singular: 'call', plural: 'calls' },
},
});
export const historyRetention = feature({
identifier: 'history-retention',
name: 'History retention (days)',
type: 'CUSTOMIZABLE',
});
export const pro = plan({
identifier: 'pro',
name: 'Pro',
product: 'my-app',
entitlements: [
{ feature: 'history-retention', value: 30 },
{ feature: 'api-calls', value: 10000, reset: 'EVERY_MONTH', hardLimit: false },
],
prices: [
{
priceType: 'PAID',
currency: 'USD',
freeTrial: false,
trialPeriod: 0,
enabled: true,
taxBehavior: 'EXCLUSIVE',
chargeCatalogPrice: [
{
feature: null,
priceModel: 'FLAT',
paymentType: 'ADVANCE_COMMITMENT',
reset: 'NEVER',
charges: [
{ chargePeriod: 'MONTHLY', priceData: { amount: 29 } },
{ chargePeriod: 'YEARLY', priceData: { amount: 290 } },
],
},
],
},
],
});
```
The builders are typed: your editor autocompletes every field, and a misspelled or wrongly-typed field is a **compile-time error** with a "did you mean" suggestion — validation happens before any API call.
How the CLI reads the file: every export created by `product()` / `feature()` / `plan()` is collected, regardless of its export name. Other exports (helper constants, functions) are ignored, so you can organize the file however you like — split values, comment freely, generate plans in a loop. Duplicate identifiers within a kind are a hard error.
***
## The identity rule
Every cross-reference in the format — `plan.product`, `entitlements[].feature` — is an **identifier slug, never a UUID**. Identifiers are lowercase URL-safe slugs matching `^[a-z0-9][a-z0-9-_]*$` (for example `pro`, `api-calls`, `seats_v2`).
The Kelviq API sometimes wants UUIDs internally; the CLI resolves identifiers to UUIDs at sync time so your config file stays portable — the same file works against sandbox and production, where the same catalog has different UUIDs.
The plan lifecycle (draft → published) is also deliberately absent: the config describes **desired state**, not deployment state. Lifecycle is handled at sync time.
***
## product()
| Field | Type | Required | Description |
| - | - | - | - |
| `identifier` | slug | yes | Stable identifier, the join key across environments. |
| `name` | string | yes | Display name. |
| `taxCode` | enum | yes | One of: `saas`, `saas_business`, `software`, `videocontent`, `informationservice`, `ebook`, `digitalgraphic`, `videogame`, `eservice`, `training`. |
| `description` | string | no | Free-text description. |
***
## feature()
| Field | Type | Required | Description |
| - | - | - | - |
| `identifier` | slug | yes | Stable identifier, referenced from plan entitlements. |
| `name` | string | yes | Display name. |
| `type` | enum | yes | `BOOLEAN` (on/off), `CUSTOMIZABLE` (a setting the plan configures, such as days of history retention), or `METER` (a counted quantity — usage that resets, or seats a customer buys). Seats are a `METER`, not `CUSTOMIZABLE`: only a meter can carry a per-unit price and take a quantity at checkout — see [seat-based pricing](/product-catalog/seat-based-pricing). |
| `description` | string | no | Free-text description. |
| `featureDetails` | object | for `METER` | Type-specific detail payload, passed through to the API. A `METER` feature needs `featureSubType` (`PRE_AGGREGATED_USAGE`) and `units` (`{ singular, plural }`): `kelviq push` refuses to create one without them, before writing anything, because the API rejects it. See [Create a feature](/product-catalog/create-a-feature). |
| `meter` | object | no | Meter configuration for `METER` features, passed through to the API. |
| `metadata` | object | no | Arbitrary key-value metadata. |
***
## plan()
| Field | Type | Required | Description |
| - | - | - | - |
| `identifier` | slug | yes | Stable identifier. |
| `name` | string | yes | Display name. |
| `product` | slug | yes | Identifier of the parent product. |
| `description` | string | no | Free-text description. |
| `isVisible` | boolean | no | Whether the plan is publicly visible. |
| `license` | object | no | License-key issuance settings for orders on this plan — see below. |
| `entitlements` | array | no | What the plan grants — see below. |
| `prices` | array | no | The plan's price set — see below. |
| `metadata` | object | no | Arbitrary key-value metadata. |
### Entitlements
Each entry grants a feature to the plan:
| Field | Type | Required | Description |
| - | - | - | - |
| `feature` | slug | yes | Identifier of the granted feature. |
| `value` | boolean or number | no | The grant: `true`/`false` for `BOOLEAN` features, a number for limits. |
| `hasUnlimitedUsage` | boolean | no | Grant unlimited usage instead of a numeric value. Omit `value` when this is `true`; `kelviq pull` writes unlimited entitlements this way. |
| `reset` | enum | no | Usage reset cadence: `NEVER`, `EVERY_DAY`, `EVERY_28_DAYS`, `EVERY_MONTH`, `EVERY_QUARTER`, `EVERY_YEAR`. |
| `hardLimit` | boolean | no | Whether usage is blocked at the limit. |
| `usageAlerts` | object | no | Alert configuration, passed through to the API. |
Entitlements accept additional keys beyond these — the shape varies by feature type, and unrecognized keys are passed through to the API rather than rejected.
> [!NOTE]
>
> Some enum values (for example `EVERY_28_DAYS`) are only available when enabled for your account. The CLI's enum fields autocomplete the standard values but accept any string: values it doesn't recognize are passed through verbatim, and the API validates them when you push. This means new server-side values work without a CLI update.
### License keys
When [license keys](/product-catalog/license-keys) are enabled on a plan, every order generates a key. The `license` object holds the plan-level issuance settings — the same controls as the dashboard's **License keys** section:
```ts theme={null}
export const team = plan({
identifier: 'team',
name: 'Team',
product: 'my-app',
license: {
enabled: true,
activationLimitEnabled: true,
activationLimit: 5, // up to 5 devices per key
hasExpiry: true,
durationValue: 12,
durationUnit: 'MONTH', // keys expire 12 months after purchase
},
});
```
| Field | Type | Required | Description |
| - | - | - | - |
| `enabled` | boolean | no | Whether orders for this plan issue license keys. |
| `activationLimitEnabled` | boolean | no | Cap how many devices one key can be activated on. When `false`, activations are unlimited. |
| `activationLimit` | integer ≥ 1 | no | The cap, when `activationLimitEnabled` is `true`. |
| `hasExpiry` | boolean | no | Whether keys expire. When `false`, keys never expire. |
| `durationValue` | integer ≥ 1 | no | How long a key stays valid after purchase, in `durationUnit`s. |
| `durationUnit` | enum | no | `DAY`, `MONTH`, or `YEAR`. |
The object is compared and sent as one unit: `kelviq push` shows the old and new license config side by side and sends the whole object when anything in it differs. A plan that **omits** `license` leaves the remote license settings untouched, so a config file that doesn't mention license keys never disables them. Additional keys are passed through to the API.
Individual issued keys — activating, validating, or deactivating a customer's key — are per-customer runtime operations, not catalog state. They live in the API, the SDKs, and the [MCP server](/guides/mcp-server), not in this file.
### Prices
The price envelope is validated; the charge structures inside it are deliberately loose and passed through to the API as-is:
| Field | Type | Required | Description |
| - | - | - | - |
| `priceType` | enum | yes | `FREE`, `PAID`, or `CUSTOM`. |
| `currency` | string | no | ISO currency code, e.g. `USD`. |
| `freeTrial` | boolean | no | Whether the price includes a free trial. |
| `trialPeriod` | number | no | Trial length in days. |
| `taxBehavior` | enum | no | `INCLUSIVE`, `EXCLUSIVE`, or `UNSPECIFIED`. |
| `enabled` | boolean | no | Whether the price is available for purchase. |
| `chargeCatalogPrice` | array of objects | no | The full charge structure (price models, tiers, billing periods). Passed through verbatim — see the plan-prices endpoints in the [API Reference](/api-reference/introduction) for the shape. |
> [!NOTE]
>
> A pulled config reproduces your remote prices in full, including nested charge structures. To author one by hand, start from `kelviq init --template saas|usage|license` or pull an existing plan and adapt it. Fields you leave out — `freeTrial`, `taxBehavior`, a charge's `paymentType` or `reset` — take the server's defaults, and `kelviq push` compares prices only on the fields you set, so leaving them out never shows up as a change.
***
## Schemas as values
Everything the builders validate against is exported from `@kelviq/cli/config` if you want to reuse it — `productDefSchema`, `featureDefSchema`, `planDefSchema`, `entitlementDefSchema`, `priceDefSchema`, `licenseDefSchema`, `kelviqConfigSchema`, the enums (`taxCodeSchema`, `featureTypeSchema`, `priceTypeSchema`, `resetSchema`, `taxBehaviorSchema`, `durationUnitSchema`, `identifierSchema`), and their TypeScript types (`ProductDef`, `FeatureDef`, `PlanDef`, `LicenseDef`, and so on). They're standard [Zod](https://zod.dev) schemas.
# Kelviq CLI
Source: https://docs.kelviq.com/cli/overview
Pricing-as-code for Kelviq — define your products, features, and plans in TypeScript and sync them with your account from the terminal.
> [!NOTE]
>
> **The Kelviq CLI is in beta.** It's fully functional — and safe by design, with previews and confirmations before every write — but commands, flags, and the `--json` output shape may still change between releases. Pin an exact version in CI and review the release notes before upgrading.
> [!TIP]
>
> Working with an AI coding agent? The [Agent Toolkit](/guides/agent-toolkit)'s `pricing-as-code` skill teaches agents this exact workflow — including the rule that agents preview diffs freely but never apply changes without your approval.
The Kelviq CLI (`@kelviq/cli`) lets you manage your pricing catalog as **code** instead of dashboard clicks. Your products, features, plans, entitlements, and prices live in a single typed TypeScript file — `kelviq.config.ts` — that you can review, diff, and version-control like the rest of your codebase.
```ts theme={null}
import { product, feature, plan } from '@kelviq/cli/config';
export const app = product({
identifier: 'my-app',
name: 'My App',
taxCode: 'saas',
});
export const historyRetention = feature({
identifier: 'history-retention',
name: 'History retention (days)',
type: 'CUSTOMIZABLE',
});
export const pro = plan({
identifier: 'pro',
name: 'Pro',
product: 'my-app',
entitlements: [{ feature: 'history-retention', value: 30 }],
});
```
The loop is complete in both directions: `kelviq pull` turns a live environment into a config file, and `kelviq push` deploys a config file back — with a diff preview, draft-first writes, and explicit gates before anything customer-facing changes. `kelviq promote` moves your whole sandbox catalog to production the same way.
***
## Why pricing-as-code?
Your pricing model decides what customers are billed, what features they can reach, and what limits they hit. It is production infrastructure. But when it lives only in a dashboard, it's managed unlike any other production infrastructure you run:
* **Changes are invisible to your engineering workflow.** A plan edit doesn't show up in a pull request, doesn't get a review, and doesn't appear in `git log`. The first your team hears of it may be a support ticket.
* **There's no meaningful diff.** "What exactly changed in our Pro plan last quarter?" has no good answer when the only record is the current dashboard state.
* **Environments drift silently.** Sandbox and production start identical and slowly diverge — a limit tweaked in one, a price fixed in the other — until "it worked in sandbox" stops meaning anything.
* **The model lives in people's heads.** Understanding your own packaging means clicking through screens, plan by plan, feature by feature.
A `kelviq.config.ts` under version control changes each of those:
| Without | With pricing-as-code |
| - | - |
| Dashboard edits leave no trail | Every change is a commit — author, date, diff, and the PR discussion that approved it |
| Pricing changes skip review | Pricing changes go through the same pull-request review as any other production change |
| Sandbox/production drift is invisible | Pull both environments and `diff` them — drift is a one-command check |
| The catalog is spread across dashboard screens | The whole monetization model is one readable file — onboarding is "read this" |
| Mistakes surface at runtime, via the API | The file is **typed**: a misspelled field or invalid enum is a compile-time error with a "did you mean" suggestion, before Kelviq ever sees it |
The concepts in the file map one-to-one to Kelviq's own — products, features, plans, entitlements, prices. If you know the [core concepts](/quickstart/core-concepts), you already know the format.
***
## What you can do today
### Put your catalog under version control
If you've already built your pricing in the dashboard, one command gets it into git:
```shell theme={null}
kelviq pull
git add kelviq.config.ts && git commit -m "Snapshot pricing catalog"
```
From here on, re-running `kelviq pull --force` and committing captures every catalog change as a diff. Run it on a schedule in CI and dashboard edits stop being invisible — they become commits your team can read.
### Catch drift between sandbox and production
Pull both environments and compare:
```shell theme={null}
kelviq pull -o sandbox.config.ts --force
kelviq pull --prod -o production.config.ts --force
diff sandbox.config.ts production.config.ts
```
Because the config format references everything by stable `identifier` slugs — never per-environment UUIDs — the two files are directly comparable. A clean diff means your environments genuinely match; anything else shows you exactly where they don't. Run it before a launch, after a migration, or whenever "it worked in sandbox" needs verifying.
### Review pricing changes like code — then deploy them
Propose a pricing change by editing `kelviq.config.ts` in a pull request — the reviewer sees exactly what changes: the new limit, the removed entitlement, the price that swapped. After the merge, deploying is one command with a preview built in:
```shell theme={null}
kelviq push --dry-run # exactly what would change, zero writes
kelviq push # apply as drafts, after showing the diff and asking
kelviq push --publish # and publish the changed plans, after a second confirmation
```
Everything push writes is a **draft** by default — nothing a customer sees changes until you publish, and migrating existing customers to new entitlements or pricing always requires its own explicit flags. Pricing changes get the full GitOps treatment: PR → review → merge → push, with the dashboard as a viewer rather than the editor.
### Promote sandbox to production
Build and test your pricing in sandbox, then move it to production in one reviewed step:
```shell theme={null}
kelviq promote --dry-run # read-only: exactly what production would change
kelviq promote # apply it, drafts first, confirmation required
```
Promote matches resources across environments by identifier — no files, no UUID bookkeeping — and inherits every one of push's safety rails.
### Give your AI tools your pricing model
A typed, self-contained TypeScript file is something coding assistants are genuinely good at working with — ask one to "add a Team plan between Pro and Enterprise with 25 seats" and the builders' types keep it honest; anything invalid fails to compile. Pair the CLI with the [Kelviq MCP server](/guides/mcp-server) and your assistant can read the config for context *and* apply catalog changes through the API today.
### Start a new project from a template
```shell theme={null}
kelviq init
```
Writes a complete starter `kelviq.config.ts` to edit by hand — useful when you're designing pricing for a new product and want to sketch the model in code (with autocomplete and validation) before anything exists in Kelviq. `--template usage` and `--template license` start from a metered or a license-key catalog instead of the default SaaS one.
***
## How it fits with the rest of Kelviq
Each Kelviq surface has a distinct job — the CLI doesn't replace the others:
| Tool | Use it for |
| - | - |
| **CLI** (this) | Managing the **catalog itself** — the definition of your products, features, plans, and prices — as versioned code. |
| [Dashboard](https://app.kelviq.com) | Visual management, analytics, customer operations, feature renames — and reviewing the drafts push creates. |
| [Backend](/backend-integration/node-sdk) & [frontend SDKs](/frontend-integration/react-sdk) | Your **application's** runtime integration — checkouts, entitlement checks, usage reporting inside your product. |
| [MCP server](/guides/mcp-server) | Driving the Kelviq API conversationally from Claude, Cursor, or any MCP client. |
| [REST API](/api-reference/introduction) | Everything, programmatically — the layer all of the above are built on. |
A useful rule of thumb: SDKs are how your **product** talks to Kelviq at runtime; the CLI is how your **team** manages what Kelviq is configured to sell.
***
## Installation
Requires Node.js 18 or newer.
```shell theme={null}
npm install -g @kelviq/cli
```
Verify the install:
```shell theme={null}
kelviq --version
```
***
## Quickstart
### Step 1: Authenticate
```shell theme={null}
kelviq login
```
`login` opens the dashboard's [API keys page](https://app.kelviq.com/settings/api-keys) in your browser and prompts you to paste a **Server API Key**. Input is masked and the key is stored locally with owner-only file permissions. If the key is already in your project's `.env.local` or `.env` as `KELVIQ_SERVER_API_KEY`, skip this step: the CLI reads it from there.
The CLI targets your **sandbox** environment by default. To store a production key too, run `kelviq login --prod`. See [Environments & authentication](/cli/environments) for how keys are stored and how to use environment variables instead (for example, in CI).
### Step 2: Pull your catalog
```shell theme={null}
kelviq pull
```
`pull` fetches your sandbox catalog — products, features, plans, entitlements, and prices — and writes it as a `kelviq.config.ts` in the current directory. If you've already set up pricing in the dashboard, this is the fastest way to get it under version control.
### Step 3: Or start from scratch
```shell theme={null}
kelviq init
```
`init` writes a starter `kelviq.config.ts` you can edit by hand. The file is plain TypeScript with full autocomplete — misspell a field and the compiler tells you before Kelviq ever sees it.
### Step 4: Check where you're pointed
```shell theme={null}
kelviq env --check
```
Prints which environment the CLI targets, which keys are configured and which env files were read, and with `--check` confirms each key is accepted by the API — useful before any command that touches your account. Keys can also live in the project's `.env.local` or `.env`: every command reads `KELVIQ_*` variables from there, so an app's existing env file is enough.
### Step 5: Make a change and deploy it
Edit the config — bump a limit, add a plan — then:
```shell theme={null}
kelviq push --dry-run # see exactly what would change
kelviq push # apply it as drafts, after confirmation
```
When you're happy, `kelviq push --publish` makes the changed plans live, and `kelviq promote` carries the whole catalog from sandbox to production.
***
## The commands
| Command | What it does |
| - | - |
| [`kelviq init`](/cli/commands#kelviq-init) | Write a starter `kelviq.config.ts`. |
| [`kelviq login`](/cli/commands#kelviq-login) | Paste and store a Server API key. |
| [`kelviq logout`](/cli/commands#kelviq-logout) | Remove stored API keys. |
| [`kelviq env`](/cli/commands#kelviq-env) | Show the configured environment and key status. |
| [`kelviq pull`](/cli/commands#kelviq-pull) | Write your remote catalog to `kelviq.config.ts`. |
| [`kelviq push`](/cli/commands#kelviq-push) | Deploy a `kelviq.config.ts`: diff, confirm, draft-first writes, optional publish and prune. |
| [`kelviq promote`](/cli/commands#kelviq-promote) | Move the sandbox catalog to production with the same preview and gates. |
| [`kelviq status`](/cli/commands#kelviq-status) | Show the live catalog: products, features, each plan's latest version with price and entitlement counts. |
| [`kelviq webhook`](/cli/commands#kelviq-webhook) | Register the app's webhook endpoint and write its signing secret into an env file without printing it. |
| [`kelviq discount`](/cli/commands#kelviq-discount) | Create and list discount codes, with the product given by identifier. |
See the full [command reference](/cli/commands) for every flag, and the [`kelviq.config.ts` reference](/cli/kelviq-config) for the file format.
***
## What's coming
* **Browser-based login** — a pairing flow that mints a scoped key from your dashboard session, replacing paste-a-key.
# Managing payment methods
Source: https://docs.kelviq.com/customer-portal/managing-payment-methods
How your customers add, update, and remove payment methods
## Multiple customer records with one email
More than one customer record can use the same email address. Each record has a unique customer ID and keeps its own subscriptions, payment methods, and billing details.
If a customer sees more than one record in the portal, they should select the record connected to the subscription they want to manage.
## How Kelviq chooses a payment method
When a subscription renews, Kelviq first charges the payment method selected when the subscription was created.
If that payment method fails because it has expired, has insufficient funds, or cannot be processed, Kelviq uses the saved default payment method as a fallback.
## How customers pay a failed card invoice
If an automatic card payment fails, your customer gets an email with a link to pay the invoice. They can also open **Billing settings** in the customer portal sidebar to add or update a payment method.
Paying an invoice manually does not turn off automatic payments. The customer's payment authorization remains active for future renewals.
See [Failed subscription payments](/product-catalog/subscriptions#failed-subscription-payments) for the card retry schedule.
## How customers manage payment methods
### Add a payment method
1. The customer opens **Settings** from the main menu and selects **Billing**.
2. They select the customer record they want to update.
3. They click **Add Payment Method**.
4. They enter the payment details and click **Save**.
The new payment method appears under **Saved payment methods**.
### Set the default payment method
The default payment method is used as a fallback if the payment method attached to a subscription fails.
1. The customer opens **Billing settings** in the customer portal sidebar.
2. They find the payment method they want to use as the default.
3. They click the star icon next to it.
The portal adds a **Default** badge to the selected payment method.
### Delete a payment method
Customers cannot delete their current default payment method. They must set another payment method as the default first.
1. The customer opens **Billing settings** in the customer portal sidebar.
2. They find the payment method they want to remove.
3. They click the trash icon next to it.
# Customer portal
Source: https://docs.kelviq.com/customer-portal/overview
A self-serve hub for your customers to manage subscriptions and access content.
Kelviq provides a hosted customer portal.
This is a self-serve environment. Your customers manage their own subscriptions, access files, and handle billing details. You don't need to build this. It ensures you don't have to manually answer support tickets for basic tasks like upgrading plans or downloading invoices.
## Access and login
The portal uses passwordless, secure access.
**1. Purchase and invite**
When a customer completes a purchase, they get access immediately.
**2. Login**
Customers enter their email address on your portal login page.
**3. Secure entry**
We send a one-time access code to their email. They enter this code to log in. No passwords to remember.
## My orders
This is the home screen. It lists everything the customer owns. They can click on a specific product to see details.
### Product details
Inside a specific product, customers find their deliverables.
* **Digital downloads**
Access files, e-books, or software binaries.
* **External links**
Private links to Discord servers or Notion templates.
* **License management**
View license keys. If you enforce seat limits, customers can see active devices and revoke licenses to free up seats for new team members.
## Subscription management
Customers have control over their lifecycle without contacting you.
* **Change plans**
Upgrade to a higher tier or downgrade.
* **Pause and cancel**
Pause a subscription temporarily or stop it entirely. With [retention offers](/customer-portal/retention) on, customers see an offer before they cancel.
* **Payment methods**
Update credit card details or switch methods for future renewals.
## Billing settings
This section handles compliance and admin tasks.
### Invoices and receipts
Customers can view their full payment history. They can download PDF invoices and receipts for their own accounting.
### Account details
This is where they manage the legal side of the account.
* **Tax IDs**
Update billing addresses and VAT/Tax IDs.
* **Refund status**
Track the status of partial or full refunds.
* **Account transfer**
Transfer ownership of the account and subscription to a different email address.
# Retention offers
Source: https://docs.kelviq.com/customer-portal/retention
Ask customers why they're cancelling and make an offer to keep them
When a customer cancels a subscription in the [customer portal](/customer-portal/overview), Kelviq asks why, then shows the offer you picked for that reason: a discount, a pause, or a link to your support team. If the customer says no, they continue to cancel.
Set it up in **Settings → Retention** and turn on **Enable retention offer**.
## What the customer sees
**1. They pick a reason**
**2. They see your offer**
The offer depends on the reason. Here, **Not using it enough** leads to a pause.
**3. They confirm or keep the subscription**
A customer who declines the offer chooses when access ends: at the end of the billing period, immediately, or on a date they pick. If you've turned on written feedback, your question appears here too.
## Set up your offers
Set each offer up once. Then choose which reasons show it.
| Offer | What you set | What happens if the customer accepts |
| - | - | - |
| Discount | A percentage off and how many billing cycles it lasts | The plan stays the same and the next payments are discounted. After that, the price goes back to normal |
| Pause | Which lengths to offer: 1, 3, or 6 months | Billing and access stop for the period they choose, then resume. See [Pause a subscription](/product-catalog/subscriptions#pause-a-subscription) |
| Support | A link to a booking page, live chat, or your help site | They go to that link. Nothing changes on the subscription |
Use the eye icon next to an offer to preview it.
## Match offers to reasons
Under **Offers by cancellation reason**, pick an offer for each reason, or **No offer** to let the customer go straight to the final step.
| Reason | Example offer |
| - | - |
| Too expensive | Discount |
| Not using it enough | Pause |
| Missing features | Support |
| Switching to another product | No offer |
| Technical issues | Support |
| Poor support experience | Support |
| Business or project ended | No offer |
| Other | No offer |
> [!TIP]
>
> Offer what fits the reason. A customer who isn't using the product won't stay for a discount, but might come back after a pause.
## Ask for written feedback
Turn on **Written feedback** to ask one open question before the customer confirms, such as "What could we do better?". Answering is optional. The answer is saved as the cancellation comment on the subscription.
## When an offer isn't available
An offer the customer can't use still appears, greyed out, with the reason. A customer sees an offer only once per subscription unless you change the repeat policy below, and offers aren't available on free or manually billed subscriptions.
A pause has to cover at least one full billing period, so a 1-month pause isn't offered on a yearly plan, and a yearly plan usually gets no pause offer at all. Only an active subscription can be paused: not one on trial, past due, or already scheduled to cancel.
## Advanced settings
| Setting | Options |
| - | - |
| Resume billing behavior | **Reset billing cycle** (default) charges a full period on the day the subscription resumes and makes that the new billing day. **Keep billing day** charges nothing on resume and waits for the original billing day. A customer who resumes inside a period they've already paid for is never charged again, whichever you choose |
| Offer repeat policy | **Once per subscription** (default), **After previous offer ends**, or **Unlimited**. Controls whether a customer who accepted an offer can accept it again on a later cancellation. A plan change doesn't reset this |
## Related documentation
* [Customer portal](/customer-portal/overview)
* [Subscriptions](/product-catalog/subscriptions)
* [Discounts](/product-catalog/discounts)
# Overview
Source: https://docs.kelviq.com/customers-management/overview
View and manage customer details, subscriptions, and entitlements.
Managing customers sits at the center of Kelviq. Each customer connects directly to their subscriptions, the plans behind them, and the features they own. You need to understand these relationships to handle the full customer lifecycle.
## View customer list
Select **Customers** in the main navigation to see your list.
You can do a few things here.
* **Search** by name, email, or identifier.
* **Add a new customer** with **New customer** in the top right.
* **Manage a customer** by clicking their row to see details.
## Add a new customer
You can create records manually.
**1. Open the modal**
Click **+ New customer** in the top right of the list page.
**2. Fill in details**
You need to provide a few key pieces of info.
* **Customer name** is required. Use the person's full name or company name.
* **Identifier** is the unique ID the API uses. We auto-generate this based on the name, but you can edit it. Linking this to the ID in your own database is usually a good idea.
* **Email address** is optional.
**3. Create**
Click **Create** to finish.
If you are adding a batch of people, toggle on **Create more**. This keeps the window open so you can add the next one immediately.
> [!NOTE]
>
> More than one customer record can use the same email address, but every record must have a unique **Identifier**. The API calls this value `customerId`.
>
> When recreating a test customer, you can reuse the email address, but you must provide a new Identifier. An Identifier cannot be reused after its customer is archived. If you receive a `customer already exists` error, check the Identifier first.
## Manage existing customers
You can edit details or revoke access from the list view.
### Edit a customer
Click the **three dots** on the right side of the customer row and select **Edit**.
You can update the **Customer name** and **Email address**. The Identifier is fixed after creation and cannot be changed.
### Archive a customer
Archiving makes a customer inactive and revokes their access. Click the **three dots** and select **Archive**.
You will see a confirmation warning. Click **Confirm** to proceed.
Kelviq archives customers; it does not hard-delete them. The archived record keeps its Identifier, so that value cannot be reused. To create another customer with the same email address, use a new Identifier.
> [!WARNING]
>
> You cannot archive a customer with an active subscription. You must cancel their subscription first.
## Customer details
Click on any customer row to open their full profile.
This page holds the source of truth for that user. You can see their unique Billing ID and timestamps for when they joined or were last updated.
### Subscriptions
This section lists active and past plans. It shows the status, such as Active or Canceled, and the relevant dates. For a canceled subscription, the date it was canceled appears alongside the status.
### Files, links, and license keys
The customer detail page shows the deliverables the customer received through their plans:
* **Files** — View and download digital files available to the customer.
* **Links** — Open private or external resource links attached to the plan.
* **License keys** — View issued license keys and use the available license-management controls.
These sections let support teams confirm access without opening each order separately.
For catalog setup, see [Digital Downloads](/product-catalog/digital-downloads), [Links](/product-catalog/links), and [License Key Management](/product-catalog/license-keys).
### Entitlements
This view shows exactly what the customer can do right now based on their plan.
**Overrides**
You often need to make exceptions for specific users. You can do that here without changing the underlying plan.
* Change the value of a specific feature.
* Update the usage limit for a Meter feature.
Changes made here apply only to this specific customer.
# JavaScript SDK
Source: https://docs.kelviq.com/frontend-integration/js-sdk
Documentation for the Kelviq JavaScript SDK
The `@kelviq/js-sdk` is a lightweight, plain TypeScript library designed for interacting with Kelviq entitlement and pricing services. It allows you to:
* Fetch all feature entitlements for a specific organization and customer.
* Cache these entitlements client-side for efficient and repeated access.
* Check if a user has access to a particular feature.
* Retrieve specific entitlement details, including boolean flags, numeric configurations, and metered usage data.
* Fetch product offering and pricing data for display on pricing pages.
* Format prices with locale-aware currency formatting.
* Automatically populate pricing into DOM elements via data attributes.
* Manually refresh entitlement and pricing data from the server.
> [!NOTE]
>
> If you are using React, you can use the [React SDK](/frontend-integration/react-sdk) instead.
### Installation
Install the SDK using your preferred package manager or include it directly via CDN.
```bash theme={null}
npm install @kelviq/js-sdk
# or
yarn add @kelviq/js-sdk
# or
pnpm add @kelviq/js-sdk
```
**CDN Installation:**
```html theme={null}
```
### Basic Usage
Get started with the SDK in just a few lines of code.
```typescript theme={null}
import kelviqSDK from '@kelviq/js-sdk';
// Initialize the SDK (fetches entitlements automatically)
const kq = kelviqSDK({
customerId: "your-customer-id",
accessToken: "your-access-token",
});
// Wait for the initial fetch to complete
await kq.ready();
// Check if user has access to a feature
if (kq.hasAccess('premium-features')) {
console.log("User has access to premium features!");
}
// Get specific entitlement details
const emailQuota = kq.getEntitlement('email-sends');
if (emailQuota && emailQuota.hasAccess) {
console.log(`Emails remaining: ${emailQuota.remaining}`);
}
```
## API Reference
Complete documentation of all SDK methods and configuration options.
### Initialization
Create and configure your SDK instance with the required parameters.
> [!WARNING]
>
> **Security Warning:** Never use your Server API Key in the browser. Use the **Client API Key** which is safe to expose in client-side code. You can find both keys in the [API keys](https://app.kelviq.com/settings/api-keys) section of your Kelviq dashboard.
```typescript theme={null}
// Initialize the SDK
const kq = kelviqSDK({
customerId: "your-customer-id",
accessToken: "your-access-token",
});
```
You can also initialize the SDK with just a `productId` to fetch pricing data only (without entitlements):
```typescript theme={null}
// Initialize for pricing only
const kq = kelviqSDK({
productId: "your-product-id",
accessToken: "your-access-token",
});
await kq.ready();
const pricing = kq.getPricing();
```
Or use both `customerId` and `productId` together:
```typescript theme={null}
// Initialize for both entitlements and pricing
const kq = kelviqSDK({
customerId: "your-customer-id",
productId: "your-product-id",
accessToken: "your-access-token",
});
await kq.ready();
// Both entitlements and pricing are now available
```
#### Options
| Option | Type | Default | Description |
| - | - | - | - |
| `customerId` | `string` | — | Unique identifier for the customer (required for entitlements) |
| `productId` | `string` | — | Product identifier for fetching pricing data (required for pricing) |
| `accessToken` | `string` | — | Authentication token for API requests |
| `environment` | `sandbox\|production` | 'production' | The environment to use. If you want to use the sandbox, you must provide this. |
| `initializeAndFetch` | `boolean` | `true` | Automatically fetch data on initialization |
| `onError` | `(error: Error) => void` | — | Error callback function |
| `mainApiUrl` | `string` | — | Optional override for the main API base URL (used by pricing) |
> [!NOTE]
>
> At least one of `customerId` or `productId` must be provided.
### Core Methods
#### `hasAccess(featureId: string): boolean`
Check if the user has access to a specific feature. Returns `false` if the feature doesn't exist or data hasn't been fetched.
```typescript theme={null}
if (kq.hasAccess('premium-features')) {
// Show premium features
showPremiumUI();
}
```
#### `getEntitlement(featureId: string): Entitlement | null`
Get the aggregated entitlement for a specific feature. Returns the unified `Entitlement` object which includes the `.items` array of raw API objects.
```typescript theme={null}
// Boolean entitlement
const canUseAnalytics = kq.getEntitlement('analytics');
if (canUseAnalytics?.hasAccess) {
enableAnalytics();
}
// Metered entitlement
const emailQuota = kq.getEntitlement('email-sends');
if (emailQuota?.hasAccess && emailQuota.remaining !== null && emailQuota.remaining > 0) {
console.log(`Usage: ${emailQuota.currentUsage} / ${emailQuota.usageLimit}`);
console.log(`Emails remaining: ${emailQuota.remaining}`);
}
```
#### `getEntitlements(): Record | null`
Get all aggregated entitlements as a map keyed by `featureId`.
```typescript theme={null}
const allEntitlements = kq.getEntitlements();
if (allEntitlements) {
Object.entries(allEntitlements).forEach(([featureId, entitlement]) => {
console.log(`${featureId}: ${entitlement.hasAccess ? 'Access granted' : 'Access denied'}`);
});
}
```
#### `getRawEntitlement(featureId: string): RawEntitlement[] | null`
Get the raw, un-aggregated API items for a specific feature. Useful when you need per-item details like `resetAt` or `hardLimit`.
```typescript theme={null}
const rawItems = kq.getRawEntitlement('email-sends');
if (rawItems) {
rawItems.forEach(item => {
console.log(`Reset at: ${item.resetAt}, Limit: ${item.usageLimit}`);
});
}
```
#### `getRawEntitlements(): RawEntitlementsApiResponse | null`
Get the full raw API response including the `customerId` wrapper, exactly as received from the server.
```typescript theme={null}
const raw = kq.getRawEntitlements();
if (raw) {
console.log(`Customer: ${raw.customerId}`);
console.log(`Total items: ${raw.entitlements.length}`);
}
```
#### `ready(): Promise`
Wait for the initial fetch (triggered by `initializeAndFetch: true`) to complete. Resolves immediately if no initial fetch was triggered or if the data is already available.
```typescript theme={null}
const kq = kelviqSDK({
customerId: "your-customer-id",
accessToken: "your-access-token",
});
await kq.ready();
// Entitlements are now available
if (kq.hasAccess('premium-features')) {
showPremiumUI();
}
```
#### `fetchAllEntitlements(forceRefresh?: boolean): Promise>`
Manually trigger a network request to refresh the entitlements. If a fetch is already in progress, the same promise is returned (calls are deduplicated).
```typescript theme={null}
// Fetch fresh data
try {
const entitlements = await kq.fetchAllEntitlements(true);
console.log('Entitlements refreshed:', entitlements);
} catch (error) {
console.error('Failed to refresh entitlements:', error);
}
```
#### `isLoading(): boolean`
Check if entitlements are currently being fetched.
```typescript theme={null}
if (kq.isLoading()) {
showLoadingSpinner();
} else {
hideLoadingSpinner();
}
```
#### `getLastError(): Error | null`
Get the last error that occurred during entitlement fetching.
```typescript theme={null}
const lastError = kq.getLastError();
if (lastError) {
console.error('Last SDK error:', lastError.message);
}
```
#### `clearCache(): void`
Clear the cached entitlements.
```typescript theme={null}
kq.clearCache();
// Next call to hasAccess or getEntitlement will need a new fetch
```
### Pricing Methods
#### `fetchPricing(forceRefresh?: boolean): Promise`
Fetch product offering and pricing data. Requires `productId` to be set. Results are cached; use `forceRefresh` to bypass the cache.
```typescript theme={null}
const pricing = await kq.fetchPricing();
console.log(`Plans: ${pricing.plans.length}`);
console.log(`Currency: ${pricing.currencySymbol}`);
```
#### `getPricing(): RawPricingApiResponse | null`
Get cached pricing data. Returns `null` if not yet fetched.
```typescript theme={null}
const pricing = kq.getPricing();
if (pricing) {
pricing.plans.forEach(plan => {
console.log(`${plan.displayName}: ${plan.price.priceType}`);
});
}
```
#### `getPlan(identifier: string): RawPricingPlan | null`
Find an enabled plan by its identifier from cached pricing data.
```typescript theme={null}
const starterPlan = kq.getPlan('starter');
if (starterPlan) {
const monthlyCharge = starterPlan.price.charges.find(c => c.chargePeriod === 'MONTHLY');
console.log(`Monthly price: ${monthlyCharge?.priceData.amount}`);
}
```
#### `isPricingLoading(): boolean`
Check if pricing data is currently being fetched.
#### `getLastPricingError(): Error | null`
Get the last error from a pricing fetch.
#### `clearPricingCache(): void`
Clear cached pricing data and reset pricing state.
```typescript theme={null}
kq.clearPricingCache();
// Next call to getPricing will need a new fetch
```
### `renderPricing()` — DOM Binding
Automatically populate pricing into HTML elements using `data-kq-price` attributes. The SDK scans the DOM for elements with these attributes and fills in formatted prices.
```html theme={null}
Loading...
Loading...
Loading...
```
```typescript theme={null}
const kq = kelviqSDK({
productId: "your-product-id",
accessToken: "your-access-token",
});
await kq.ready();
kq.renderPricing(); // Scans DOM and populates data-kq-price elements
```
* `data-kq-price` — the plan identifier (e.g., `"starter"`, `"pro"`)
* `data-kq-period` — the charge period (e.g., `"MONTHLY"`, `"YEARLY"`)
* Free plans display `"Free"` instead of a price
* Disabled or missing plans result in empty text
You can scope the scan to a container and pass formatting options:
```typescript theme={null}
kq.renderPricing({
container: document.getElementById('pricing-section'),
formatOptions: { compact: true },
});
```
### `kqFormatPrice` Utility
A standalone utility for formatting prices with locale-aware currency formatting.
```typescript theme={null}
import { kqFormatPrice } from '@kelviq/js-sdk';
kqFormatPrice(49.99, '$'); // "$49.99"
kqFormatPrice(1299, '$', { compact: true }); // "$1.3K"
kqFormatPrice(100, '€', { locale: 'de-DE' }); // "€100"
kqFormatPrice(29, '$', { includeCurrencySymbol: false }); // "29"
```
| Option | Type | Default | Description |
| - | - | - | - |
| `compact` | `boolean` | `false` | Use compact notation (e.g., "1.2K") |
| `locale` | `string` | `'en-US'` | Locale for number formatting |
| `includeCurrencySymbol` | `boolean` | `true` | Include the currency symbol |
| `pricingLocale` | `string` | — | Fallback locale (from pricing API response) |
## Entitlement Types
The SDK uses a single, unified `Entitlement` interface. When the API returns duplicate `featureId`s (e.g., from Subscriptions + Top-ups), they are aggregated automatically.
```typescript theme={null}
interface Entitlement {
featureId: string;
featureType: "METER" | "BOOLEAN" | "CUSTOMIZABLE";
hasAccess: boolean; // METER: remaining === null || remaining > 0; others: true if any item grants access
hardLimit: boolean; // true if any item has a hard limit
currentUsage: number; // METER: summed across items; CUSTOMIZABLE: from first item; BOOLEAN: 0
usageLimit: number | null; // METER: summed across items; CUSTOMIZABLE: from first item; BOOLEAN: null
remaining: number | null; // METER: usageLimit - currentUsage; CUSTOMIZABLE: from first item; BOOLEAN: null
items: RawEntitlement[]; // The raw array of original API objects for this featureId
}
```
Per-item details such as `resetAt` and `hardLimit` are available on each item in the `items` array.
## Pricing Types
The pricing API returns a rich data structure with plans, charges, features, and billing periods.
```typescript theme={null}
interface RawPricingApiResponse {
organizationId: number;
countryCode: string;
pricingLocale: string;
currencyCode: string;
currencySymbol: string;
currencyConversionRate: number;
baseCurrencyCode: string;
baseCurrencySymbol: string;
plans: RawPricingPlan[];
subscription: { hasPreviousSubscription: boolean };
isCustomerExists: boolean;
billingPeriods: RawPricingBillingPeriod[];
}
interface RawPricingPlan {
name: string;
identifier: string;
displayName: string;
displayDescription: string;
price: RawPricingPrice;
features: RawPricingFeature[];
enabled: boolean;
shouldHighlight: boolean;
// ... additional fields
}
interface RawPricingPrice {
priceType: 'FREE' | 'PAID';
charges: RawPricingCharge[];
freeTrial: boolean;
trialPeriod: number;
currency: string;
}
interface RawPricingCharge {
chargePeriod: string; // e.g., "MONTHLY", "YEARLY"
priceData: { amount: number };
}
```
All pricing types are exported from the SDK: `RawPricingApiResponse`, `RawPricingPlan`, `RawPricingPrice`, `RawPricingCharge`, `RawPricingFeature`, `RawPricingBillingPeriod`.
## Examples
Real-world usage patterns and common implementation scenarios.
### Feature Gating
Control access to features based on user entitlements.
```typescript theme={null}
// Simple feature gate
if (kq.hasAccess('beta-features')) {
showBetaFeatures();
}
// Conditional rendering
const canUseAdvancedSearch = kq.hasAccess('advanced-search');
return (
(config: ApiRequestConfig): Promise> {
const response = await fetch(config.url, {
method: config.method || 'GET',
headers: {
'Authorization': `Bearer ${config.accessToken}`,
'Content-Type': 'application/json',
...config.headers
},
body: config.body ? JSON.stringify(config.body) : undefined
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
return {
status: response.status,
statusText: response.statusText,
data: await response.json()
};
}
// Use custom API request
const kq = kelviqSDK({
customerId: "user123",
accessToken: "token456"
}, customApiRequest);
```
## TypeScript Support
Full TypeScript support with comprehensive type definitions.
The SDK is written in TypeScript and provides full type safety:
```typescript theme={null}
import kelviqSDK, {
KelviqClientOptions,
Entitlement,
RawEntitlement,
RawEntitlementsApiResponse
} from '@kelviq/js-sdk';
const options: KelviqClientOptions = {
customerId: "user123",
accessToken: "token456"
};
const kq = kelviqSDK(options);
// Type-safe entitlement access
const emailQuota: Entitlement | null = kq.getEntitlement('emails');
```
## Advanced Configuration
Advanced options for customizing SDK behavior and API integration.
### API Configuration
Configure API request behavior and retry logic.
```typescript theme={null}
const kq = kelviqSDK({
customerId: "user123",
accessToken: "token456",
apiConfig: {
maxRetries: 5,
timeout: 10000,
backoffBaseDelay: 2000
}
});
```
### Custom Error Handling
Implement sophisticated error handling and recovery strategies.
```typescript theme={null}
const kq = kelviqSDK({
customerId: "user123",
accessToken: "token456",
onError: (error) => {
// Send to error tracking service
Sentry.captureException(error);
// Retry logic
if (error.message.includes('network')) {
setTimeout(() => kq.fetchAllEntitlements(), 5000);
}
}
});
```
### Advanced Options
Additional configuration options for specialized use cases.
Default values are:
```typescript theme={null}
const kq = kelviqSDK({
customerId: "",
accessToken: "",
apiUrl: "https://edge.api.kelviq.com/api/v1",
entitlementsPath: "entitlements/",
apiConfig: {
maxRetries: 3,
timeout: 5000,
backoffBaseDelay: 1000
}
});
```
| Option | Type | Description |
| - | - | - |
| `apiUrl` | `string` | Base URL for the API |
| `entitlementsPath` | `string` | Path for fetching entitlements |
| `apiConfig.maxRetries` | `number` | Maximum number of retries for API requests |
| `apiConfig.timeout` | `number` | Timeout for API requests in milliseconds |
| `apiConfig.backoffBaseDelay` | `number` | Base delay for exponential backoff strategy |
## Using the Sandbox
Set `environment: "sandbox"` when you call `kelviqSDK()`, and use a sandbox Client API Key.
```typescript theme={null}
const kq = kelviqSDK({
customerId: "your-customer-id",
accessToken: "your-access-token",
environment: "sandbox"
});
```
# Promotions UI JS SDK
Source: https://docs.kelviq.com/frontend-integration/promotions-ui-js
Add purchasing power parity discounts and a localised banner to any website
The Promotions UI JS SDK automatically applies location-based discounts to prices on your page and renders a customisable banner that tells visitors about their local deal. It works with plain HTML — no framework required.
> [!NOTE]
>
> This SDK is separate from the [entitlements JS SDK](/frontend-integration/js-sdk). Use this SDK when you need PPP / country-based discount banners and price display.
***
## Installation
### 1. Add the Script
Paste this snippet just before the closing `` tag on your pricing page:
```html theme={null}
```
### 2. Initialize the SDK
Copy your promotion ID from the promotion detail page and call `init()`:
```javascript theme={null}
KQPromotionUI.init({
// Replace with your promotion ID
promotionId: "YOUR_PROMOTION_ID",
// Access token can be found in the Settings → API keys section
accessToken: "YOUR_CLIENT_ACCESS_TOKEN",
showBanner: true,
});
```
This will automatically display a discount banner if the visitor is eligible for a discount.
> [!WARNING]
>
> **Never expose your Server API Key in the browser.** Use the **Client API Key**, which is safe for client-side code. You can find both keys under **Settings → API keys** in the [Kelviq dashboard](https://app.kelviq.com/settings/api-keys).
***
## `init()` options
| Option | Type | Default | Description |
| - | - | - | - |
| `promotionId` | `string` | — | Promotion ID from the Kelviq dashboard |
| `accessToken` | `string` | — | Client API Key (Settings → API keys) |
| `showBanner` | `boolean` | `true` | Render the localised discount banner automatically |
| `environment` | `"production" \| "sandbox"` | `"production"` | Target environment |
| `baseCurrencyCode` | `string` | `"USD"` | ISO 4217 code for prices displayed on the page |
| `baseCurrencySymbol` | `string` | `"$"` | Symbol written to `data-kq-currency-symbol` elements |
| `currencyDisplay` | `"symbol" \| "code" \| "name"` | `"symbol"` | How the currency is formatted via `Intl.NumberFormat` |
| `showDecimal` | `boolean` | `false` | Include the decimal portion in formatted prices |
| `minimumDecimalDigits` | `number` | `2` | Minimum fraction digits (0–2) |
| `maximumDecimalDigits` | `number` | `2` | Maximum fraction digits (0–2) |
| `banner.*` | object | — | Customization for the discount banner |
| `banner.unStyled` | boolean | false | if true, no styling will be applied to the banner |
| `banner.addCloseIcon` | boolean | true | Shows or hides the close button. Works only when the close button is enabled in the promotion's banner settings in Kelviq. |
| `banner.placement` | `top\|bottom` | 'top' | The placement of the discount banner |
| `banner.container` | string | null | The container for the discount banner |
| `banner.backgroundColor` | string | '#f0f0f0' | The background color of the discount banner |
| `banner.fontColor` | string | '#333333' | The font color of the discount banner |
| `banner.borderRadius` | string | '0px' | The border radius of the discount banner |
| `banner.fontSize` | string | '14px' | The font size of the discount banner |
***
## Auto price update
After `init()` resolves, every element with `data-kq-price` on the page is automatically updated with the discounted price for the visitor's country.
### Basic usage
```html theme={null}
```
> [!TIP]
>
> The original-price element is hidden by default. The SDK shows it automatically when a discount is active and hides it when the visitor's country has no discount.
### Price container attributes
| Attribute | Value | Description |
| - | - | - |
| `data-kq-price` | `number` | Base price — the discounted value is computed and written to child elements |
| `data-kq-original-price-display` | `number` | Original (pre-discount) price; hidden when there is no active discount |
| `data-kq-rel` | `string` | Links a price element and its original-price element so they update together |
| `data-kq-show-decimal` | `"true" \| "false"` | Per-element decimal override (falls back to `showDecimal` from `init()`) |
| `data-kq-currency-display` | `"symbol" \| "code" \| "name"` | Per-element currency format |
| `data-kq-minimum-decimal-digits` | `number` | Per-element minimum fraction digits (0–2) |
| `data-kq-maximum-decimal-digits` | `number` | Per-element maximum fraction digits (0–2) |
### Sub-element attributes
Place these inside a price container to receive individual parts of the formatted price:
| Attribute | Example output |
| - | - |
| `data-kq-currency-symbol` | `$` |
| `data-kq-price-integer` | `49` |
| `data-kq-price-decimal` | `99` |
| `data-kq-price-decimal-separator` | `.` |
| `data-kq-currency-code` | `USD` |
| `data-kq-price-formatted` | `$49.99` |
***
## JS API
All methods return Promises and require `init()` to have been called first.
### `getUpdatedPrice(price, options?)`
Computes the discounted price and returns a `PriceObject` without touching the DOM.
```javascript theme={null}
const result = await KQPromotionUI.getUpdatedPrice(100, { showDecimal: true });
console.log(result.formattedPrice); // "$80.00"
console.log(result.price); // 80
```
**Parameters**
| Parameter | Type | Description |
| - | - | - |
| `price` | `number` | Base price to apply the discount to |
| `options` | `Partial` | Optional overrides (same fields as `init()`) |
**Returns — `PriceObject`**
| Field | Type | Description |
| - | - | - |
| `price` | `number` | Final price after discount |
| `formattedPrice` | `string` | Fully formatted string, e.g. `$80.00` |
| `integerPart` | `string` | Integer portion only, e.g. `80` |
| `decimalPart` | `string` | Decimal digits only, e.g. `00` |
| `decimalSeparator` | `string` | Locale-specific separator, e.g. `.` |
| `currencySymbol` | `string` | Currency symbol, e.g. `$` |
| `currencyCode` | `string` | ISO 4217 code, e.g. `USD` |
| `apiResponse` | `PricingData` | Full API response including country, percentage, and widgets |
***
### `updatePriceElement(element, options?)`
Updates a specific DOM element with the computed discounted price. The element **must** have a `data-kq-price` attribute. All elements linked to it via `data-kq-rel` are updated as well.
```javascript theme={null}
const el = document.getElementById("pro-price");
const result = await KQPromotionUI.updatePriceElement(el, { showDecimal: true });
console.log(result.formattedPrice);
```
**Parameters**
| Parameter | Type | Description |
| - | - | - |
| `element` | `HTMLElement` | Must have `data-kq-price` attribute |
| `options` | `Partial` | Optional overrides |
Returns a `PriceObject` (same shape as `getUpdatedPrice`).
***
### `updatePrice(configs[])`
Batch-update multiple elements, optionally rendering each with an HTML template.
```javascript theme={null}
await KQPromotionUI.updatePrice([
{
element: document.getElementById("monthly"),
price: 29,
options: { showDecimal: false },
template: "{{formattedPrice}} /mo",
},
{
element: document.getElementById("annual"),
price: 199,
options: { showDecimal: true },
template: "{{formattedPrice}} /yr",
},
]);
```
**Config object fields**
| Field | Type | Description |
| - | - | - |
| `element` | `HTMLElement` | Target element — its `innerHTML` is replaced with the rendered template |
| `price` | `number` | Base price |
| `options` | `Partial` | Optional overrides |
| `template` | `string` | HTML string with `{{key}}` placeholders |
**Available template variables** (any field from `PriceObject`):
`{{price}}` · `{{formattedPrice}}` · `{{integerPart}}` · `{{decimalPart}}` · `{{decimalSeparator}}` · `{{currencySymbol}}` · `{{currencyCode}}`
Returns `Promise` — one entry per config.
***
## CSS hooks
The SDK adds classes to `document.body` that you can target in your stylesheets:
| Class | Added when |
| - | - |
| `kq-discount-applied` | An active discount > 0% exists for the visitor's country |
| `kq-has-parity-banner` | The discount banner has been injected into the page |
```css theme={null}
/* Show a sale badge only when a discount is active */
.sale-badge { display: none; }
body.kq-discount-applied .sale-badge { display: inline-block; }
/* Add top padding so content isn't hidden under the banner */
body.kq-has-parity-banner main { padding-top: 60px; }
```
***
## Sandbox
Set `environment: "sandbox"` to test against the Kelviq sandbox environment.
```javascript theme={null}
KQPromotionUI.init({
promotionId: "YOUR_PROMOTION_ID",
accessToken: "YOUR_CLIENT_ACCESS_TOKEN",
environment: "sandbox",
});
```
Use sandbox API keys (available under **Settings → API keys** with the Sandbox toggle enabled) so real visitor data is never affected during testing.
# React Promotions UI
Source: https://docs.kelviq.com/frontend-integration/react-promotions-ui
Add purchasing power parity discounts and a localised banner to your React app
The `@kelviq/react-promotions-ui` SDK provides React components for displaying location-based promotional banners and dynamically discounted prices. It handles API communication, discount calculation, and currency formatting out of the box.
* A **React Context Provider** (`KQProvider`) to fetch and share promotion data
* A **banner component** (`KQBanner`) with template variables and full styling control
* **Price components** for formatted display of discounted prices
* **Granular price components** for building fully custom price layouts
> [!NOTE]
>
> This SDK is separate from the [entitlements React SDK](/frontend-integration/react-sdk) and the [React UI SDK](/frontend-integration/react-ui). Use this SDK when you need PPP / country-based discount banners and price display in a React app.
***
## Installation
```bash theme={null}
npm install @kelviq/react-promotions-ui
# or
yarn add @kelviq/react-promotions-ui
```
Requires `react` and `react-dom` as peer dependencies (v17, v18, or v19).
***
## Quick start
Wrap your app with `KQProvider` and place `KQBanner` where you want the banner to appear.
```tsx theme={null}
import { KQProvider, KQBanner } from '@kelviq/react-promotions-ui';
function App() {
return (
);
}
```
> [!WARNING]
>
> **Never expose your Server API Key in the browser.** Use the **Client API Key**, which is safe for client-side code. You can find both keys under **Settings → API keys** in the [Kelviq dashboard](https://app.kelviq.com/settings/api-keys).
***
## `KQProvider`
The provider initializes the SDK, fetches promotion data from the Kelviq API, and makes it available to all child components via React Context.
### Props
| Prop | Type | Default | Description |
| - | - | - | - |
| `promotionId` | `string` | `''` | The promotion ID from the Kelviq dashboard |
| `accessToken` | `string` | `''` | Client API Key (Settings → API keys) |
| `kqIdentifier` | `string` | `''` | Optional Kelviq identifier for the request |
| `environment` | `'production' \| 'sandbox'` | `'production'` | Set to `'sandbox'` to use the sandbox API |
| `baseCurrencyCode` | `string` | `'USD'` | ISO 4217 currency code used for formatting |
| `baseCurrencySymbol` | `string` | `'$'` | Currency symbol for display |
| `config` | `object` | `{}` | Advanced configuration (see below) |
### Advanced config
The optional `config` prop accepts:
| Field | Type | Default | Description |
| - | - | - | - |
| `apiUrl` | `string` | — | Override the default API endpoint |
| `onError` | `(error: Error) => void` | — | Error callback for API failures |
| `maxRetries` | `number` | `3` | Maximum retry attempts for failed requests |
| `timeout` | `number` | `5000` | Request timeout in milliseconds |
### Sandbox
Set `environment` to `'sandbox'` to test against the Kelviq sandbox environment:
```tsx theme={null}
{/* ... */}
```
***
## `KQBanner`
Displays a location-aware promotional banner. The banner message is configured in the Kelviq dashboard and supports template variables that are automatically replaced with real data.
```tsx theme={null}
import { KQBanner } from '@kelviq/react-promotions-ui';
// Basic — uses styles from the dashboard
console.log('Banner closed')}
/>
```
### Props
| Prop | Type | Default | Description |
| - | - | - | - |
| `backgroundColor` | `string` | *(from API)* | Banner background color |
| `fontColor` | `string` | *(from API)* | Banner text color |
| `borderRadius` | `string` | *(from API)* | Banner border radius |
| `fontSize` | `string` | *(from API)* | Banner font size |
| `unStyled` | `boolean` | *(from API)* | If `true`, no default styles are injected |
| `addCloseIcon` | `boolean` | *(from API)* | Show a close button on the banner |
| `className` | `string` | `''` | Custom CSS class name |
| `onClose` | `() => void` | — | Callback fired when the banner is closed |
> [!TIP]
>
> Props override the corresponding values returned by the API. If you don't pass a prop, the dashboard-configured value is used.
### Template variables
The banner message (configured in the dashboard) supports these placeholders:
| Variable | Replaced with | Example |
| - | - | - |
| `{country}` | Visitor's country name | `United States` |
| `{country_flag}` | Country flag image (CDN-hosted SVG) | 🇺🇸 *(rendered as `![]()
`)* |
| `{coupon_code}` | The discount coupon code | `SAVE20` |
| `{discount_percentage}` | The discount percentage | `20` |
**Example message:**
```
Hello {country_flag} You're visiting from {country}! Use code "{coupon_code}" for {discount_percentage}% off.
```
### CSS hooks
The banner adds classes to `document.body` that you can target in your stylesheets:
| Class | Added when |
| - | - |
| `kq-has-banner` | The banner is visible on the page |
```css theme={null}
/* Add top padding so content isn't hidden behind the banner */
body.kq-has-banner main {
padding-top: 60px;
}
```
### Unstyled mode
Set `unStyled={true}` to remove all default styles and apply your own CSS from scratch. Target the banner using the `kq-banner` CSS class or the `data-testid="kq-banner"` attribute.
```tsx theme={null}
{/* Promotional banner */}
);
}
```
***
## Support
For technical support and questions, reach out at [hi@kelviq.com](mailto:hi@kelviq.com).
# React SDK
Source: https://docs.kelviq.com/frontend-integration/react-sdk
Documentation for the Kelviq React SDK
The `@kelviq/react-sdk` provides a seamless way to integrate Kelviq entitlement management into your React applications.
## Overview
* A **React Context Provider** (`KelviqProvider`) to initialize and configure the SDK.
* **Hooks** to easily access entitlement status, pricing, and data within your components.
* **Conditional rendering components** to show or hide UI elements based on feature access.
* **Pricing components** (`KQPrice`, `KQFeatureList`) for displaying localized plan pricing and features.
* Automatic and manual **data fetching** and caching mechanisms.
The SDK fetches all entitlements for a given organization and customer, caches them, and makes them available throughout your application via React Context and custom hooks.
## **2. Installation**
Install the SDK using npm or yarn:
```bash theme={null}
npm install @kelviq/react-sdk
# or
yarn add @kelviq/react-sdk
```
You will also need `react` as a peer dependency.
## **3. Setup & Configuration**
### `KelviqProvider`
The core of the SDK is the `KelviqProvider`. You need to wrap your application (or the relevant part of it) with this provider. It initializes the SDK and makes entitlement data available to its children components via context.
```tsx theme={null}
// In your App.tsx or main application entry point
import React from 'react';
import { KelviqProvider } from '@kelviq/react-sdk';
const App = () => {
return (
);
};
const MyAppContent = () => {
return (
My Application
);
};
export default App;
```
### Required Props for `KelviqProvider`
* `accessToken: string | null`
* Your **Client API Key** for authenticating requests to the Kelviq API. This key is safe to expose in client-side code. You can find it in the [API keys](https://app.kelviq.com/settings/api-keys) section of your Kelviq dashboard. Never use your Server API Key in client-side code.
### Optional Props for `KelviqProvider`
**Optional Props**
* `customerId?: string`
* The ID of the customer for whom entitlements are being fetched. This will be sent as a query parameter (`customer_id`). Required for entitlements, subscriptions, and customer data. Optional when only using pricing.
* `productId?: string`
* The product identifier for fetching pricing/offering data. Required when `fetchPricingOnMount` is `true`.
* `plansEnabled?: string`
* Comma-separated list of plan identifiers to include in the pricing response. When omitted, all active plans for the product are returned. Example: `"pro,enterprise"`.
* `apiUrl: string`
* The base URL for your Kelviq API. For example, `https://edge.api.kelviq.com/api/v1`.
* `environment: 'sandbox' | 'production'`
* The environment to use. If you want to use the sandbox, you must provide this.
* `entitlementsPath: string`
* The specific path for the endpoint that returns all entitlements for a customer. This path will be appended to `apiUrl`. For example, `entitlement-check` or `user-entitlements`.
* `config?: KelviqApiBehaviorOptions`
* An optional object to configure more advanced behaviors of the SDK.
### **Configuration Object (**`config: KelviqApiBehaviorOptions`**)**
This optional object can contain the following properties:
* `onError?: (error: Error) => void`
* A callback function that will be invoked if an error occurs during the API request for entitlements.
* `maxRetries?: number`
* The maximum number of times to retry a failed API request. Defaults to `3`.
* `timeout?: number`
* Timeout for API requests in milliseconds. Defaults to `5000`.
* `backoffBaseDelay?: number`
* Base delay (in milliseconds) for the exponential backoff strategy used in retries. Defaults to `1000`.
* `fetchEntitlementsOnMount?: boolean`
* Defaults to `true`. If true, entitlements are fetched automatically when the `KelviqProvider` mounts.
* Set to `false` if you want to control the initial fetch manually using the `refreshAllEntitlements` function from the `useKelviq` hook.
* `fetchSubscriptionsOnMount?: boolean`
* Defaults to `false`. If true, the customer's subscription data is fetched automatically when the `KelviqProvider` mounts.
* When enabled, data is available via the `useSubscriptions()` hook or `subscriptions` from `useKelviq()`.
* `fetchCustomerOnMount?: boolean`
* Defaults to `false`. If true, customer data is fetched automatically when the `KelviqProvider` mounts.
* When enabled, data is available via the `useCustomer()` hook or `customer` from `useKelviq()`.
* `fetchPricingOnMount?: boolean`
* Defaults to `false`. If true, pricing/offering data is fetched automatically when the `KelviqProvider` mounts. Requires `productId` to be set on the provider.
* When enabled, data is available via the `usePricing()` hook or `pricing` from `useKelviq()`.
## **4. Fetching Entitlements**
### **Automatic Fetching on Mount**
By default (`fetchEntitlementsOnMount: true` in the `config` prop, or if `config` or this specific option is omitted), the SDK will attempt to fetch all entitlements for the specified `customerId` as soon as the `KelviqProvider` is mounted.
The `isLoading` state from `useKelviq()` will be `true` during this initial fetch.
### **Manual Fetching**
If `fetchEntitlementsOnMount` is set to `false`, or if you need to re-fetch entitlements at any point (e.g., after a user action that might change their entitlements), you can use the `refreshAllEntitlements` function.
**Code Example**
```tsx theme={null}
import { useKelviq } from '@kelviq/react-sdk';
function MyComponent() {
const { refreshAllEntitlements, isLoading, error } = useKelviq();
const handleRefresh = async () => {
try {
await refreshAllEntitlements();
console.log("Entitlements refreshed!");
} catch (e) {
console.error("Failed to refresh entitlements:", e);
}
};
return (
{error && Error: {error.message}
}
{/* ... rest of your component ... */}
);
}
```
## **5. Accessing Entitlement Data (Hooks)**
The SDK provides several hooks to access entitlement data and SDK state.
### `useKelviq()`
This is the primary hook to access the SDK's context.
* **Returns:** `KelviqContextValue` object containing:
* `allEntitlements: AsyncState`: The state object for all fetched entitlements.
* `data`: An `EntitlementMap` (a `Record`) where keys are `featureId`s, or `null` if not loaded or error.
* `isLoading`: Boolean indicating if the `allEntitlements` data is currently being fetched/refreshed.
* `error`: An `Error` object if the last fetch failed, otherwise `null`.
* `refreshAllEntitlements: () => Promise`: Function to manually trigger a re-fetch of all entitlements.
* `getEntitlements: () => EntitlementMap`: Returns all aggregated entitlements as a `Record` keyed by `featureId`. Returns an empty object if data has not been fetched yet.
* `getEntitlement: (featureId: string) => Entitlement | null`: Returns the aggregated entitlement for a given `featureId`, or `null` if not found or not yet loaded.
* `getRawEntitlements: () => EntitlementsResponse | null`: Returns the raw API response with `customerId` and the un-aggregated `entitlements` array (duplicate `featureId` entries are preserved). Returns `null` if data has not been fetched yet.
* `getRawEntitlement: (featureId: string) => EntitlementsResponse | null`: Returns the raw API response filtered to a specific `featureId`, with `customerId` and only the matching entries.
* `hasAccess: (featureId: string) => boolean`: A utility function to quickly check access for a feature. Returns `true` if access is granted, `false` if denied, feature not found, or data is not yet loaded.
* `updateEntitlement: (featureId: string, data: Partial<...>) => void`: Updates a cached entitlement in-place. Accepts partial data (excluding `featureId`, `featureType`, and `items`). Automatically recalculates `remaining` when `usageLimit` or `currentUsage` are updated.
* `subscriptions: AsyncState`: The state object for the customer's subscriptions. Only populated when `fetchSubscriptionsOnMount` is `true` or after calling `refreshSubscriptions()`.
* `refreshSubscriptions: () => Promise`: Function to manually trigger a re-fetch of the customer's subscriptions.
* `customer: AsyncState`: The state object for customer data. Only populated when `fetchCustomerOnMount` is `true` or after calling `refreshCustomer()`.
* `refreshCustomer: () => Promise`: Function to manually trigger a re-fetch of the customer data.
* `pricing: AsyncState`: The state object for pricing/offering data with localized currency. Only populated when `fetchPricingOnMount` is `true` or after calling `refreshPricing()`.
* `refreshPricing: () => Promise`: Function to manually trigger a re-fetch of the pricing data.
* `isLoading: boolean`: A global loading state indicating if the SDK is performing its initial configured fetch or a refresh operation.
* `error: Error | null`: A global error state reflecting any error from the last fetch operation initiated by the provider.
* `customerId: string`: The customer ID passed to the provider.
* `environment: string`: The environment (`'production'` or `'sandbox'`) passed to the provider.
* `apiUrl: string`: The resolved API URL used by the provider.
* `entitlementsPath: string`: The entitlements path passed to the provider.
***
#### `hasAccess(featureId)`
Quickly check if a customer has access to a feature.
```tsx theme={null}
const { hasAccess } = useKelviq();
const canUse = hasAccess("premium-reporting");
```
> **Response**
>
> ```json theme={null}
> true
> ```
***
#### `getEntitlement(featureId)`
Returns the aggregated entitlement for a given feature. When the API returns multiple entries for the same `featureId` (e.g. from different subscriptions), the SDK groups them and exposes aggregated totals at the top level.
```tsx theme={null}
const { getEntitlement } = useKelviq();
const entitlement = getEntitlement("api-calls-quota");
```
> **Response — Metered Entitlement**
>
> ```json theme={null}
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "currentUsage": 150,
> "usageLimit": 1000,
> "remaining": 850,
> "hardLimit": true,
> "items": [
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-06-01T00:00:00Z",
> "hardLimit": false,
> "usageLimit": 500,
> "currentUsage": 100,
> "remaining": 400
> },
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-07-01T00:00:00Z",
> "hardLimit": true,
> "usageLimit": 500,
> "currentUsage": 50,
> "remaining": 450
> }
> ]
> }
> ```
> **Response — Boolean Entitlement**
>
> ```json theme={null}
> {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": null,
> "remaining": null,
> "hardLimit": false,
> "items": [
> {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true
> }
> ]
> }
> ```
> **Response — Customizable Entitlement**
>
> ```json theme={null}
> {
> "featureId": "max-items-per-page",
> "featureType": "CUSTOMIZABLE",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": 50,
> "remaining": 50,
> "hardLimit": false,
> "items": [
> {
> "featureId": "max-items-per-page",
> "featureType": "CUSTOMIZABLE",
> "hasAccess": true,
> "usageLimit": 50,
> "currentUsage": 0,
> "remaining": 50
> }
> ]
> }
> ```
***
#### `getEntitlements()`
Returns all aggregated entitlements as a `Record` keyed by `featureId`.
```tsx theme={null}
const { getEntitlements } = useKelviq();
const entitlements = getEntitlements();
```
> **Response**
>
> ```json theme={null}
> {
> "api-calls-quota": {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "currentUsage": 150,
> "usageLimit": 1000,
> "remaining": 850,
> "hardLimit": true,
> "items": [
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-06-01T00:00:00Z",
> "hardLimit": false,
> "usageLimit": 500,
> "currentUsage": 100,
> "remaining": 400
> },
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-07-01T00:00:00Z",
> "hardLimit": true,
> "usageLimit": 500,
> "currentUsage": 50,
> "remaining": 450
> }
> ]
> },
> "enable-dark-mode": {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": null,
> "remaining": null,
> "hardLimit": false,
> "items": [
> {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true
> }
> ]
> }
> }
> ```
***
#### `getRawEntitlements()`
Returns the raw, un-aggregated API response with `customerId`. Duplicate `featureId` entries from multiple subscriptions are preserved as-is.
```tsx theme={null}
const { getRawEntitlements } = useKelviq();
const raw = getRawEntitlements();
```
> **Response**
>
> ```json theme={null}
> {
> "customerId": "cust_456",
> "entitlements": [
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-06-01T00:00:00Z",
> "hardLimit": false,
> "usageLimit": 500,
> "currentUsage": 100,
> "remaining": 400
> },
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-07-01T00:00:00Z",
> "hardLimit": true,
> "usageLimit": 500,
> "currentUsage": 50,
> "remaining": 450
> },
> {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true
> }
> ]
> }
> ```
***
#### `getRawEntitlement(featureId)`
Returns the raw API response filtered to a specific `featureId`. Useful for accessing per-subscription data for a single feature.
```tsx theme={null}
const { getRawEntitlement } = useKelviq();
const raw = getRawEntitlement("api-calls-quota");
```
> **Response**
>
> ```json theme={null}
> {
> "customerId": "cust_456",
> "entitlements": [
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-06-01T00:00:00Z",
> "hardLimit": false,
> "usageLimit": 500,
> "currentUsage": 100,
> "remaining": 400
> },
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-07-01T00:00:00Z",
> "hardLimit": true,
> "usageLimit": 500,
> "currentUsage": 50,
> "remaining": 450
> }
> ]
> }
> ```
***
#### `updateEntitlement(featureId, data)`
Updates a cached entitlement in-place. Useful for optimistically updating the UI after a usage increment without waiting for a full refresh. The `remaining` field is automatically recalculated when `usageLimit` or `currentUsage` are updated.
```tsx theme={null}
const { updateEntitlement } = useKelviq();
// After the user performs an action that consumes usage
updateEntitlement("api-calls-quota", { currentUsage: 151 });
```
> **Updated Entitlement**
>
> ```json theme={null}
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "currentUsage": 151,
> "usageLimit": 1000,
> "remaining": 849,
> "hardLimit": true,
> "items": [...]
> }
> ```
Accepts `Partial>`. You can update any combination of `hasAccess`, `currentUsage`, `usageLimit`, and `remaining`.
### `useAllEntitlements()`
A convenience hook that directly returns the `allEntitlements` state object.
* **Returns:** `AsyncState`
```tsx theme={null}
import { useAllEntitlements } from '@kelviq/react-sdk';
function EntitlementsList() {
const { data: entitlementsMap, isLoading, error } = useAllEntitlements();
if (isLoading) return Loading all entitlements...
;
if (error) return Error loading entitlements: {error.message}
;
if (!entitlementsMap) return No entitlements data.
;
return (
{Object.values(entitlementsMap).map(ent => (
);
}
```
> **Response — entitlementsMap**
>
> ```json theme={null}
> {
> "api-calls-quota": {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "currentUsage": 150,
> "usageLimit": 1000,
> "remaining": 850,
> "hardLimit": true,
> "items": [...]
> },
> "enable-dark-mode": {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": null,
> "remaining": null,
> "hardLimit": false,
> "items": [...]
> },
> "max-items-per-page": {
> "featureId": "max-items-per-page",
> "featureType": "CUSTOMIZABLE",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": 50,
> "remaining": 50,
> "hardLimit": false,
> "items": [...]
> }
> }
> ```
### `useBooleanEntitlement(featureId: string)`
Returns the aggregated entitlement for a specific boolean feature from the cache.
* **Arguments:**
* `featureId: string`: The identifier of the boolean feature.
* **Returns:** `Entitlement | null`
```tsx theme={null}
import { useBooleanEntitlement } from '@kelviq/react-sdk';
const entitlement = useBooleanEntitlement("enable-dark-mode");
```
> **Response**
>
> ```json theme={null}
> {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": null,
> "remaining": null,
> "hardLimit": false,
> "items": [
> {
> "featureId": "enable-dark-mode",
> "featureType": "BOOLEAN",
> "hasAccess": true
> }
> ]
> }
> ```
### `useCustomizableEntitlement(featureId: string)`
Returns the aggregated entitlement for a specific customizable feature from the cache.
* **Arguments:**
* `featureId: string`: The identifier of the customizable feature.
* **Returns:** `Entitlement | null`
```tsx theme={null}
import { useCustomizableEntitlement } from '@kelviq/react-sdk';
const entitlement = useCustomizableEntitlement("max-items-per-page");
```
> **Response**
>
> ```json theme={null}
> {
> "featureId": "max-items-per-page",
> "featureType": "CUSTOMIZABLE",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": 50,
> "remaining": 50,
> "hardLimit": false,
> "items": [
> {
> "featureId": "max-items-per-page",
> "featureType": "CUSTOMIZABLE",
> "hasAccess": true,
> "usageLimit": 50,
> "currentUsage": 0,
> "remaining": 50
> }
> ]
> }
> ```
### `useMeteredEntitlement(featureId: string)`
Returns the aggregated entitlement for a specific Meter feature from the cache.
* **Arguments:**
* `featureId: string`: The identifier of the Meter feature.
* **Returns:** `Entitlement | null`
```tsx theme={null}
import { useMeteredEntitlement } from '@kelviq/react-sdk';
const entitlement = useMeteredEntitlement("api-calls-quota");
```
> **Response**
>
> ```json theme={null}
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "currentUsage": 150,
> "usageLimit": 1000,
> "remaining": 850,
> "hardLimit": true,
> "items": [
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-06-01T00:00:00Z",
> "hardLimit": false,
> "usageLimit": 500,
> "currentUsage": 100,
> "remaining": 400
> },
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-07-01T00:00:00Z",
> "hardLimit": true,
> "usageLimit": 500,
> "currentUsage": 50,
> "remaining": 450
> }
> ]
> }
> ```
### `useSubscriptions()`
Returns the customer's subscription data. Only populated when `fetchSubscriptionsOnMount` is enabled in the provider config, or after calling `refreshSubscriptions()` from `useKelviq()`.
* **Returns:** `AsyncState`
```tsx theme={null}
import { useSubscriptions } from '@kelviq/react-sdk';
function SubscriptionInfo() {
const { data: subscriptions, isLoading, error } = useSubscriptions();
if (isLoading) return Loading subscriptions...
;
if (error) return Error: {error.message}
;
if (!subscriptions) return No subscriptions found.
;
return (
{subscriptions.map(sub => (
);
}
```
> **Response — subscriptions**
>
> ```json theme={null}
> [
> {
> "id": "sub-uuid-1",
> "externalSubscriptionId": "ext-sub-123",
> "startDate": "2025-01-01T00:00:00Z",
> "endDate": null,
> "billingPeriodStartTime": "2025-06-01T00:00:00Z",
> "billingPeriodEndTime": "2025-07-01T00:00:00Z",
> "amount": "49.99",
> "recurrence": "monthly",
> "currency": "USD",
> "status": "active",
> "product": {
> "name": "Pro Plan",
> "identifier": "pro-plan"
> },
> "plan": {
> "name": "Pro Monthly",
> "identifier": "pro-monthly"
> },
> "features": [
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "usageLimit": 1000,
> "currentUsage": 150,
> "remaining": 850
> }
> ],
> "trialDaysRemaining": null,
> "customerId": "cust_456"
> }
> ]
> ```
> [!NOTE]
>
> You must enable `fetchSubscriptionsOnMount: true` in the provider's `config` prop, or call `refreshSubscriptions()` manually, for this hook to return data.
### `useCustomer()`
Returns the customer data. Only populated when `fetchCustomerOnMount` is enabled in the provider config, or after calling `refreshCustomer()` from `useKelviq()`.
* **Returns:** `AsyncState`
```tsx theme={null}
import { useCustomer } from '@kelviq/react-sdk';
function CustomerProfile() {
const { data: customer, isLoading, error } = useCustomer();
if (isLoading) return Loading customer...
;
if (error) return Error: {error.message}
;
if (!customer) return No customer data.
;
return (
{customer.name}
{customer.email}
{customer.billingAddress && (
{customer.billingAddress.city}, {customer.billingAddress.state}
)}
);
}
```
> **Response — customer**
>
> ```json theme={null}
> {
> "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
> "customerId": "unique-customer-id-123",
> "name": "John Doe",
> "email": "customer@example.com",
> "details": {},
> "metadata": {
> "source": "sdk_import",
> "priority": "high"
> },
> "billingAddress": {
> "country": "IN",
> "line1": "123 Main Street",
> "line2": "Apt 4B",
> "postalCode": "560001",
> "city": "Bangalore",
> "state": "Karnataka"
> },
> "createdOn": "2025-06-04T06:03:30.195790Z",
> "modifiedOn": "2025-06-04T06:03:30.195831Z"
> }
> ```
> [!NOTE]
>
> You must enable `fetchCustomerOnMount: true` in the provider's `config` prop, or call `refreshCustomer()` manually, for this hook to return data.
### `usePricing()`
Returns the pricing/offering data for the configured product. Includes localized currency information, plans, features, and billing periods. Only populated when `fetchPricingOnMount` is enabled in the provider config, or after calling `refreshPricing()` from `useKelviq()`.
* **Returns:** `AsyncState`
```tsx theme={null}
import { usePricing } from '@kelviq/react-sdk';
function PricingDisplay() {
const { data: pricing, isLoading, error } = usePricing();
if (isLoading) return Loading pricing...
;
if (error) return Error: {error.message}
;
if (!pricing) return No pricing data.
;
return (
Currency: {pricing.currencySymbol} ({pricing.currencyCode})
{pricing.plans.map(plan => (
);
}
```
> [!NOTE]
>
> You must set `productId` on the provider and enable `fetchPricingOnMount: true` in the provider's `config` prop, or call `refreshPricing()` manually, for this hook to return data.
>
> When `customerId` is provided, the pricing response includes the customer's active subscription details and the `isCustomerExists` flag. Use `plansEnabled` to filter the response to specific plans (e.g., `"pro,enterprise"`).
**Example using a specific entitlement hook:**
```tsx theme={null}
import { useBooleanEntitlement, useKelviq } from '@kelviq/react-sdk';
function FeatureSpecificComponent({ featureId }: { featureId: string }) {
const { isLoading, error } = useKelviq();
const entitlement = useBooleanEntitlement(featureId);
if (isLoading) return Loading feature {featureId}...
;
if (error) return Error loading feature {featureId}: {error.message}
;
if (entitlement && entitlement.hasAccess) {
return You have access to {featureId}!
;
} else {
return You do not have access to {featureId}.
;
}
}
```
## **6. Conditional Rendering Components**
These components provide a declarative way to render UI based on entitlement status. They internally use the respective hooks.
**Common Props:**
* `featureId: string`: The unique identifier of the feature to check.
* `children: ReactNode | ((data: Entitlement) => ReactNode)`:
* If a `ReactNode`, it's rendered when the user is entitled and conditions are met.
* If a function (render prop), it's called with the aggregated `Entitlement` data and its return value is rendered.
* `fallback?: ReactNode`: Content to render if the user is not entitled, or if data is loading (and no `loadingComponent` is provided), or if an error occurs. Defaults to `null`.
* `loadingComponent?: ReactNode`: Specific content to render while the entitlement data is loading. Overrides `fallback` during loading.
### `ShowWhenBooleanEntitled`
Renders children if the boolean feature is enabled (`hasAccess: true`).
```tsx theme={null}
import { ShowWhenBooleanEntitled } from '@kelviq/react-sdk';
Checking theme settings...}
fallback={Dark mode is not available.
}
>
{(entitlementData) => (
Advanced settings for {entitlementData.featureId} are visible!
)}
```
> **Render Prop Data (entitlementData)**
>
> ```json theme={null}
> {
> "featureId": "show-advanced-settings",
> "featureType": "BOOLEAN",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": null,
> "remaining": null,
> "hardLimit": false,
> "items": [
> {
> "featureId": "show-advanced-settings",
> "featureType": "BOOLEAN",
> "hasAccess": true
> }
> ]
> }
> ```
### `ShowWhenCustomizableEntitled`
Renders children if the customizable feature is enabled (`hasAccess: true`).
```tsx theme={null}
import { ShowWhenCustomizableEntitled } from '@kelviq/react-sdk';
Loading display settings...}
fallback={Default item limit applies.
}
>
{(entitlementData) => (
You have access to {entitlementData.featureId}.
)}
```
> **Render Prop Data (entitlementData)**
>
> ```json theme={null}
> {
> "featureId": "max-items-per-page",
> "featureType": "CUSTOMIZABLE",
> "hasAccess": true,
> "currentUsage": 0,
> "usageLimit": 50,
> "remaining": 50,
> "hardLimit": false,
> "items": [
> {
> "featureId": "max-items-per-page",
> "featureType": "CUSTOMIZABLE",
> "hasAccess": true,
> "usageLimit": 50,
> "currentUsage": 0,
> "remaining": 50
> }
> ]
> }
> ```
### `ShowWhenMeteredEntitled`
Renders children if the Meter feature is enabled and, by default, if `remaining` usage is greater than 0 or unlimited (`usageLimit` is `null`).
* **Optional Prop:**
* `condition?: (data: Entitlement) => boolean`: A custom function to further determine if children should render based on the entitlement data.
* **Children Prop:** Can be `ReactNode` or `(data: Entitlement) => ReactNode`.
```tsx theme={null}
import { ShowWhenMeteredEntitled } from '@kelviq/react-sdk';
Loading API quota...}
fallback={API call limit reached or feature not available.
}
>
{(meterData) => (
API Calls Used: {meterData.currentUsage} / {meterData.usageLimit === null ? 'Unlimited' : meterData.usageLimit}
Remaining: {meterData.remaining === null ? 'Unlimited' : meterData.remaining}
)}
```
> **Render Prop Data (meterData)**
>
> ```json theme={null}
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "currentUsage": 150,
> "usageLimit": 1000,
> "remaining": 850,
> "hardLimit": true,
> "items": [
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-06-01T00:00:00Z",
> "hardLimit": false,
> "usageLimit": 500,
> "currentUsage": 100,
> "remaining": 400
> },
> {
> "featureId": "api-calls-quota",
> "featureType": "METER",
> "hasAccess": true,
> "resetAt": "2025-07-01T00:00:00Z",
> "hardLimit": true,
> "usageLimit": 500,
> "currentUsage": 50,
> "remaining": 450
> }
> ]
> }
> ```
## **7. Pricing Components**
The SDK provides render-prop components for displaying pricing data. These require `productId` on the provider and `fetchPricingOnMount: true` (or a manual `refreshPricing()` call).
### `KQPrice`
Renders pricing information for a specific plan and billing period. Provides a `formattedPrice` string with locale-aware number formatting and currency symbol.
**Props:**
* `planIdentifier: string`: The plan identifier to display pricing for.
* `billingPeriod: string`: The billing period to show (e.g. `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`).
* `children: (data) => ReactNode`: Render function receiving price data.
* `formatOptions?: KQFormatPriceOptions`: Options for the `formattedPrice` string.
* `loadingComponent?: ReactNode`: Shown while pricing data is loading.
* `fallback?: ReactNode`: Shown when the plan is not found or pricing data is unavailable.
```tsx theme={null}
import { KQPrice } from '@kelviq/react-sdk';
Price not available}
>
{({ formattedPrice, isFree, hasFreeTrial, trialPeriod }) => (
{formattedPrice}
{hasFreeTrial && {trialPeriod}-day free trial
}
)}
```
> **Render Prop Data**
>
> The `children` render function receives an object with:
>
> * `plan`: The full plan object (`RawPricingPlan`).
> * `charge`: The matching charge for the billing period (`RawPricingCharge | null`).
> * `amount: number`: The raw price amount.
> * `formattedPrice: string`: Locale-formatted price string (e.g. `"$49.99"`, `"Free"`).
> * `currencySymbol: string`: The currency symbol (e.g. `"$"`, `"€"`).
> * `currencyCode: string`: The currency code (e.g. `"USD"`, `"EUR"`).
> * `pricingLocale: string`: The locale used for pricing (e.g. `"en-US"`).
> * `isFree: boolean`: Whether the plan is free.
> * `hasFreeTrial: boolean`: Whether the plan has a free trial.
> * `trialPeriod: number`: Trial period in days.
#### `KQFormatPriceOptions`
Options for customizing the `formattedPrice` string:
* `compact?: boolean`: Use compact notation (e.g. `"1.2K"` instead of `"1,200"`). Defaults to `false`.
* `locale?: string`: Locale for number formatting. Defaults to the `pricingLocale` from the API.
* `includeCurrencySymbol?: boolean`: Whether to include the currency symbol. Defaults to `true`.
### `KQFeatureList`
Iterates over features for a specific plan, calling the render function for each feature.
**Props:**
* `planIdentifier: string`: The plan identifier to display features for.
* `children: (data) => ReactNode`: Render function called for each feature.
* `featureType?: 'BOOLEAN' | 'METER'`: Optional filter to show only specific feature types.
* `loadingComponent?: ReactNode`: Shown while pricing data is loading.
* `fallback?: ReactNode`: Shown when the plan is not found or has no features.
```tsx theme={null}
import { KQFeatureList } from '@kelviq/react-sdk';
No features}
>
{({ feature }) => (
{feature.displayName}
{feature.featureType === 'BOOLEAN'
? feature.value ? '✓' : '✗'
: feature.value}
)}
```
> **Render Prop Data**
>
> The `children` render function receives an object with:
>
> * `feature`: The feature object (`RawPricingFeature`) with `id`, `displayName`, `featureType`, `value`, `enabled`.
> * `plan`: The full plan object (`RawPricingPlan`).
> * `index: number`: The index of the feature in the list.
### `kqFormatPrice(amount, currencySymbol, options?)`
A standalone utility function for formatting prices. Exported from the SDK for use outside of components.
```tsx theme={null}
import { kqFormatPrice } from '@kelviq/react-sdk';
kqFormatPrice(1299.99, '$'); // "$1,299.99"
kqFormatPrice(1299.99, '$', { compact: true }); // "$1.3K"
kqFormatPrice(49.99, '€', { locale: 'de-DE' }); // "€49,99"
kqFormatPrice(49.99, '$', { includeCurrencySymbol: false }); // "49.99"
```
## **8. Key Types**
The SDK exports several types for better integration with TypeScript. Some key ones include:
* `KelviqContextValue`: The shape of the object returned by `useKelviq()`.
* `KelviqApiBehaviorOptions`: Configuration options for the `config` prop.
* `AsyncState`: Generic type for asynchronous data states (`{ data, isLoading, error }`).
* `Entitlement`: The unified entitlement type with aggregated data and an `items` array containing the raw API objects.
* `EntitlementMap`: The structure of the cached entitlements (`Record`), keyed by `featureId`.
* `EntitlementsResponse`: The raw API response shape (`{ customerId, entitlements }`) returned by `getRawEntitlements()` and `getRawEntitlement()`.
* `RawEntitlementsApiResponse` and related `Raw...` types: Represent the structure of the direct API response.
* `RawSubscriptionData`: A single subscription object as returned by the subscriptions API, including `plan`, `product`, `features`, `status`, `amount`, `recurrence`, etc.
* `RawCustomerApiResponse`: Customer data as returned by the customer API, including `id`, `customerId`, `name`, `email`, `billingAddress`, `details`, `metadata`, `createdOn`, and `modifiedOn`.
* `RawBillingAddress`: The billing address object (`country`, `line1`, `line2`, `postalCode`, `city`, `state`).
* `RawPricingApiResponse`: The full pricing/offering API response including `plans`, `currencySymbol`, `currencyCode`, `pricingLocale`, and `billingPeriods`.
* `RawPricingPlan`: A single plan with `identifier`, `displayName`, `displayDescription`, `price`, `features`, and `enabled`.
* `RawPricingFeature`: A plan feature with `id`, `displayName`, `featureType`, `value`, and `enabled`.
* `RawPricingCharge`: A charge entry with `chargePeriod` and `priceData` (containing `amount`).
* `KQFormatPriceOptions`: Options for the `kqFormatPrice` utility (`compact`, `locale`, `includeCurrencySymbol`).
You can import these types directly from the main SDK entry:
```ts theme={null}
import type {
Entitlement,
EntitlementMap,
EntitlementsResponse,
RawSubscriptionData,
RawCustomerApiResponse,
RawBillingAddress,
RawPricingApiResponse,
RawPricingPlan,
RawPricingFeature,
RawPricingCharge,
KQFormatPriceOptions,
} from '@kelviq/react-sdk';
```
## **9. Error Handling**
* **Provider Level:** The `onError` callback in `config` (`KelviqApiBehaviorOptions`) can be used to globally handle errors that occur during the entitlement fetching process initiated by the provider.
* **Context Level:** `useKelviq()` returns a global `isLoading: boolean` and `error: Error | null` state, reflecting the provider's most recent fetch operation. Use these for loading/error UI in your components.
* **`allEntitlements` Level:** The `allEntitlements` object from `useKelviq()` or `useAllEntitlements()` also carries its own `isLoading` and `error` fields within the `AsyncState` wrapper.
## **10. Example Usage**
A comprehensive example is provided within the comments of the SDK code, demonstrating provider setup and component usage. The core setup involves:
1. Wrapping your application with `KelviqProvider` and providing the required props (`customerId`, `accessToken`)
2. Using hooks like `useBooleanEntitlement` or conditional components like `ShowWhenBooleanEntitled` in your components to control UI and behavior based on entitlements.
## Using the Sandbox
If you want to use the sandbox, you need to set the `environment` option to `sandbox` in the `KelviqProvider`.
```tsx theme={null}
{/* Your app components */}
```
# React UI
Source: https://docs.kelviq.com/frontend-integration/react-ui
Documentation for the Kelviq React UI SDK - A comprehensive pricing table and paywall solution
## 1. Overview
The **Kelviq React UI SDK** provides a complete React-based solution for integrating dynamic, customizable pricing tables and paywalls into web applications. It handles fetching offering data, displaying pricing plans with multiple billing periods, managing subscriptions, and processing checkouts with full localization support.
***
## 2. Installation
Install the SDK using npm or yarn:
```bash theme={null}
npm install @kelviq/react-ui
# or
yarn add @kelviq/react-ui
```
***
## 3. Quick Start
### Basic Setup
Note: You must import the CSS file for the components to be styled correctly.
```tsx theme={null}
import { KelviqProvider, KQPricingTable } from '@kelviq/react-ui';
import '@kelviq/react-ui/dist/kq-react-ui.css';
function App() {
return (
);
}
```
### With Custom Event Handling
```tsx theme={null}
import { KelviqProvider, KQPricingTable } from '@kelviq/react-ui';
import '@kelviq/react-ui/dist/kq-react-ui.css';
function App() {
const handleCustomPriceClick = (details) => {
console.log('Custom price plan clicked:', details);
// Handle custom pricing logic
};
return (
);
}
```
***
## 4. Core Components
### 4.1. `KelviqProvider`
The top-level provider component that initializes the SDK and manages the global state.
#### Required Props
| Prop | Type | Description |
| - | - | - |
| `accessToken` | `string` | Your Kelviq access token |
| `productId` | `string` | The unique identifier of the product to display the offering for |
#### Optional Props
| Prop | Type | Default | Description |
| - | - | - | - |
| `customerId` | `string` | `undefined` | Customer identifier for personalized pricing |
| `environment` | `sandbox\|production` | 'production' | The environment to use. If you want to use the sandbox, you must provide this. |
| `checkoutSuccessUrl` | `string` | `window.location.href` | URL to redirect after successful checkout |
| `apiConfig` | `KelviqAPIConfig` | `{}` | Advanced API configuration options |
#### API Configuration Options
```tsx theme={null}
interface KelviqAPIConfig {
onError?: (error: Error) => void;
maxRetries?: number; // Default: 3
timeout?: number; // Default: 5000ms
backoffBaseDelay?: number;
offeringApiUrl?: string;
subscriptionApiUrl?: string;
checkoutApiUrl?: string;
}
```
### 4.2. `KQPricingTable`
The main pricing table component that displays all plans and handles user interactions.
#### Props
| Prop | Type | Default | Description |
| - | - | - | - |
| `customStyles` | `PricingTableStyle` | `{}` | Style overrides (colors, typography, layout). Any field you omit falls back to the SDK defaults. |
| `pricingOptions` | `Partial` | `DEFAULT_PRICING_OPTIONS` | Price-formatting options (decimals, currency symbol/code, localization). Partial objects are merged with the defaults. |
| `customActionButton` | `CustomActionButton` | `undefined` | Custom button component |
| `customCheckIcon` | `React.ReactNode` | `undefined` | Custom check icon |
| `customUnCheckIcon` | `React.ReactNode` | `undefined` | Custom uncheck icon |
| `customTooltipIcon` | `React.ReactNode` | `undefined` | Custom tooltip icon |
| `onCustomPriceClick` | `(details: PlanClickDetails) => void` | `undefined` | Callback for custom price plans |
| `renderActionButtonAfter` | `features \| price` | `price` | Render the action button after the features or the price |
| `insertElements.*` | `InsertElements` | `{}` | Insert custom elements anywhere in the pricing table |
| `insertElements.beforePlanName` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the plan name |
| `insertElements.afterPlanName` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the plan name |
| `insertElements.beforePlanDescription` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the plan description |
| `insertElements.afterPlanDescription` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the plan description |
| `insertElements.beforePrice` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the price |
| `insertElements.afterPrice` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the price |
| `insertElements.beforeFeatures` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the features |
| `insertElements.afterFeatures` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the features |
| `insertElements.beforeActionButton` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the action button |
| `insertElements.afterActionButton` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the action button |
| `insertElements.beforeSwitch` | `(activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the switch |
| `insertElements.afterSwitch` | `(activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the switch |
#### Example Usage
```tsx theme={null}
{
console.log('Custom plan selected:', details.plan.displayName);
// Handle custom pricing logic
}}
customStyles={{
style: {
cardBackgroundColor: '#f8f9fa',
buttonBackgroundColor: '#28a745',
buttonColor: '#ffffff',
titleColor: '#212529'
},
typography: {
titleFontSize: 24,
titleFontWeight: '600'
},
layout: {
gap: 20,
minWidth: 280,
maxWidth: 400
}
}}
insertElements={{
afterPrice: (plan) => {
if(plan.shouldHighlight) {
return Most popular plan;
}
return null;
}
}}
/>
```
### 4.3. `KQPlan`
Renders a list of pricing plans with billing period switching.
#### Props
| Prop | Type | Required | Description |
| - | - | - | - |
| `plans` | `OfferingPlan[]` | Yes | Array of plans to display |
| `pricingOptions` | `PricingOptions` | Yes | Price-formatting options |
| `billingPeriods` | `BillingPeriod[]` | Yes | Available billing periods |
| `countryCode` | `string` | Yes | Country code for localization |
| `currencyCode` | `string` | Yes | Currency code (e.g., "USD") |
| `currencySymbol` | `string` | Yes | Currency symbol (e.g., "\$") |
| `currencyConversionRate` | `number` | Yes | Currency conversion rate |
| `pricingLocale` | `string` | Yes | Locale for price formatting |
| `onPlanClick` | `(details: PlanClickDetails) => void` | Yes | Plan selection callback |
| `customStyles` | `PricingTableStyle` | No | Custom styling |
| `customActionButton` | `CustomActionButton` | No | Custom button component |
| `actionButtonLoadingPlanIdentifier` | `string` | No | Loading state for specific plan |
| `noStyles` | `boolean` | No | Disable default styling |
### 4.4. `KQPlanItem`
Displays a single pricing plan card.
#### Props
| Prop | Type | Required | Description |
| - | - | - | - |
| `plan` | `OfferingPlan` | Yes | Plan data to display |
| `pricingOptions` | `PricingOptions` | Yes | Price-formatting options |
| `period` | `ChargePeriodEnum` | Yes | Current billing period |
| `countryCode` | `string` | Yes | Country code |
| `currencyCode` | `string` | Yes | Currency code |
| `currencySymbol` | `string` | Yes | Currency symbol |
| `currencyConversionRate` | `number` | Yes | Conversion rate |
| `pricingLocale` | `string` | Yes | Locale for formatting |
| `onKQPlanItemClick` | `(details: PlanClickDetails) => void` | Yes | Click handler |
| `customActionButton` | `CustomActionButton` | No | Custom button |
| `actionButtonText` | `string` | No | Button text |
| `actionButtonLoading` | `boolean` | No | Loading state |
| `actionButtonDisabled` | `boolean` | No | Disabled state |
| `isActive` | `boolean` | No | Active plan indicator |
| `successText` | `string` | No | Success message |
| `noStyles` | `boolean` | No | Disable styling |
### 4.5. `KQPrice`
Renders formatted price display with currency and period information.
#### Props
| Prop | Type | Required | Description |
| - | - | - | - |
| `price` | `number` | Yes | Price amount |
| `countryCode` | `string` | Yes | Country code |
| `currencyCode` | `string` | Yes | Currency code |
| `currencySymbol` | `string` | Yes | Currency symbol |
| `currencyConversionRate` | `number` | Yes | Conversion rate |
| `pricingLocale` | `string` | Yes | Locale for formatting |
| `period` | `ChargePeriodEnum` | Yes | Billing period |
| `showDecimal` | `boolean` | Yes | Show decimal places |
| `showCurrencySymbol` | `boolean` | Yes | Show currency symbol |
| `showCurrencyCode` | `boolean` | Yes | Show currency code |
| `minimumFractionDigits` | `number` | Yes | Minimum decimal places |
| `maximumFractionDigits` | `number` | Yes | Maximum decimal places |
### 4.6. `KQFeatures`
Renders the features list for a plan.
#### Props
| Prop | Type | Required | Description |
| - | - | - | - |
| `features` | `OfferingFeature[]` | Yes | Array of features |
| `period` | `ChargePeriodEnum` | Yes | Current billing period |
| `customCheckIcon` | `React.ReactNode` | No | Custom check icon |
| `customUnCheckIcon` | `React.ReactNode` | No | Custom uncheck icon |
| `customTooltipIcon` | `React.ReactNode` | No | Custom tooltip icon |
| `onUsageChange` | `(featureId: string, quantity: number) => void` | No | Usage change handler |
> Feature tooltips are controlled per-feature by the `displayTooltipDescription` flag on each feature in the offering data, configured in your Kelviq dashboard — there is no global tooltip prop.
***
## 5. Data Types
### Core Types
```tsx theme={null}
// Billing periods
enum ChargePeriodEnum {
ONE_TIME = 'ONE_TIME',
MONTHLY = 'MONTHLY',
YEARLY = 'YEARLY',
WEEKLY = 'WEEKLY',
DAILY = 'DAILY',
THREE_MONTHS = 'THREE_MONTHS',
SIX_MONTHS = 'SIX_MONTHS'
}
// Price types
enum PriceTypeEnum {
FREE = 'FREE',
PAID = 'PAID',
CUSTOM = 'CUSTOM'
}
// Price models
enum PriceModelEnum {
FLAT = 'FLAT',
PACKAGE = 'PACKAGE',
TIERED = 'TIERED',
VOLUME = 'VOLUME'
}
// Plan structure
interface OfferingPlan {
id: string;
name: string;
displayName: string;
displayDescription: string;
identifier: string;
isArchived: boolean;
features: OfferingFeature[];
price: OfferingPlanPrice;
shouldHighlight: boolean;
enabled: boolean;
}
// Plan click details
interface PlanClickDetails {
plan: OfferingPlan;
chargePeriod: ChargePeriodEnum;
usageMap: Record;
}
// Pricing table style
interface PricingTableStyle {
style: PricingTableColorConfig;
typography: PricingTableTypographyConfig;
layout: PricingTableLayoutConfig;
}
// Price-formatting options (passed via the `pricingOptions` prop)
interface PricingOptions {
localization: boolean; // use the offering's locale/currency formatting
showDecimal: boolean; // show decimal places
minimumDecimalDigits: number; // minimum decimal places
maximumDecimalDigits: number; // maximum decimal places
showCurrencySymbol: boolean; // show the currency symbol (e.g. $)
showCurrencyCode: boolean; // show the currency code (e.g. USD)
}
```
### Color Configuration
```tsx theme={null}
interface PricingTableColorConfig {
primaryColor: string;
primaryHoverColor: string;
onPrimaryColor: string;
secondaryColor: string;
cardBackgroundColor: string;
billingSwitchBackgroundColor: string;
billingSwitchColor: string;
billingSwitchSelectedColor: string;
titleColor: string;
descriptionColor: string;
priceColor: string;
priceUnitColor: string;
pricePeriodColor: string;
featureColor: string;
dividerColor: string;
buttonBackgroundColor: string;
buttonColor: string;
buttonHoverBackgroundColor: string;
advancedMode: boolean;
}
```
### Typography Configuration
```tsx theme={null}
interface PricingTableTypographyConfig {
titleFontSize: number;
titleFontWeight: string;
descriptionFontSize: number;
descriptionFontWeight: string;
priceFontSize: number;
priceFontWeight: string;
priceUnitFontSize: number;
priceUnitFontWeight: string;
featureFontSize: number;
featureFontWeight: string;
pricePeriodFontSize: number;
pricePeriodFontWeight: string;
}
```
### Layout Configuration
```tsx theme={null}
interface PricingTableLayoutConfig {
minWidth: number;
maxWidth: number;
gap: number;
align: 'start' | 'center' | 'end';
tierSelectionType: 'switch' | 'tabs';
}
```
***
## 6. Styling and Customization
### 6.1. CSS Variables
The SDK uses CSS variables for styling. You can override these in your CSS:
```css theme={null}
:root {
/* Card & Background */
--kq-card-bg: #ffffff;
--kq-card-border-width: 1px solid;
--kq-card-border-color: 1px solid;
/* Text Colors */
--kq-title-color: #171923;
--kq-description-color: #718096;
--kq-feature-color: #171923;
/* Price Colors */
--kq-price-color: #171923;
--kq-price-unit-color: #171923;
--kq-price-period-color: #718096;
/* Button Colors */
--kq-button-bg: #1A202C;
--kq-button-hover-bg: #1A202C;
--kq-button-color: #F7FAFC;
/* Billing Switch Colors */
--kq-billing-switch-bg: #1A202C;
--kq-billing-switch-color: #F7FAFC;
--kq-billing-switch-selected-color: #F7FAFC;
/* UI Elements */
--kq-divider-color: #E2E8F0;
--kq-tooltip-bg: #2D3748;
--kq-tooltip-color: #ffffff;
/* Typography - Title */
--kq-title-size: 24px;
--kq-title-weight: 600;
/* Typography - Description */
--kq-description-size: 16px;
--kq-description-weight: 400;
/* Typography - Price */
--kq-price-size: 28px;
--kq-price-weight: 700;
--kq-price-unit-size: 32px;
--kq-price-unit-weight: 700;
--kq-price-period-size: 16px;
--kq-price-period-weight: 400;
/* Typography - Feature */
--kq-feature-size: 14px;
--kq-feature-weight: 400;
/* Layout */
--kq-min-width: 360px;
--kq-max-width: 400px;
--kq-gap: 24px;
--kq-align: center;
}
```
### 6.2. Custom Styles Object
```tsx theme={null}
const customStyles: PricingTableStyle = {
style: {
cardBackgroundColor: '#ffffff',
buttonBackgroundColor: '#28a745',
buttonColor: '#ffffff',
titleColor: '#212529',
descriptionColor: '#6c757d',
priceColor: '#000000',
featureColor: '#495057'
},
typography: {
titleFontSize: 24,
titleFontWeight: '600',
descriptionFontSize: 14,
descriptionFontWeight: '400',
priceFontSize: 32,
priceFontWeight: '700'
},
layout: {
gap: 24,
minWidth: 300,
maxWidth: 450,
align: 'center'
}
};
```
### 6.3. Price Formatting
How prices are formatted is configured entirely in the SDK via the `pricingOptions` prop. Pass only the fields you want to change — the rest fall back to `DEFAULT_PRICING_OPTIONS`:
```tsx theme={null}
{
// Open contact form or custom pricing modal
openCustomPricingModal(details.plan);
}}
/>
```
### 7.3. Subscription Management
The SDK automatically handles subscription updates:
* **New Subscriptions**: Redirects to checkout
* **Plan Upgrades/Downgrades**: Updates existing subscription
* **Free Plan Upgrades**: Handles free trial to paid conversion
### 7.4. Error Handling
```tsx theme={null}
{
console.error('kelviq Error:', error);
// Show user-friendly error message
showErrorMessage('Unable to load pricing. Please try again later.');
},
maxRetries: 3,
timeout: 10000
}}
>
```
***
## 8. Complete Example
```tsx theme={null}
import React from 'react';
import {
KelviqProvider,
KQPricingTable,
PricingTableStyle
} from '@kelviq/react-ui';
const App: React.FC = () => {
const customStyles: PricingTableStyle = {
style: {
cardBackgroundColor: '#ffffff',
buttonBackgroundColor: '#007bff',
buttonColor: '#ffffff',
buttonHoverBackgroundColor: '#0056b3',
titleColor: '#212529',
descriptionColor: '#6c757d',
priceColor: '#000000',
featureColor: '#495057',
dividerColor: '#dee2e6',
billingSwitchBackgroundColor: '#f8f9fa',
billingSwitchColor: '#6c757d',
billingSwitchSelectedColor: '#007bff'
},
typography: {
titleFontSize: 24,
titleFontWeight: '600',
descriptionFontSize: 14,
descriptionFontWeight: '400',
priceFontSize: 32,
priceFontWeight: '700',
priceUnitFontSize: 16,
priceUnitFontWeight: '400',
featureFontSize: 14,
featureFontWeight: '400',
pricePeriodFontSize: 14,
pricePeriodFontWeight: '400'
},
layout: {
gap: 24,
minWidth: 300,
maxWidth: 450,
align: 'center'
}
};
const handleCustomPriceClick = (details) => {
console.log('Custom plan selected:', details.plan.displayName);
// Open contact form or pricing calculator
window.open('/contact', '_blank');
};
return (
Choose Your Plan
Select the perfect plan for your needs
{
console.error('Pricing Error:', error);
},
timeout: 10000
}}
>
);
};
export default App;
```
***
## 9. API Endpoints
The SDK uses the following default API endpoints:
* **Product Offering API**: `https://api.kelviq.com/api/v1/monetization/product-offering/{productId}/`
* **Checkout API**: `https://api.kelviq.com/api/v1/checkout/`
* **Subscription API**: `https://api.kelviq.com/api/v1/subscriptions`
You can override these in the `apiConfig`:
```tsx theme={null}
```
***
## 10. Troubleshooting
### Common Issues
1. **Loading State**: Ensure your `accessToken` and `productId` are correct
2. **Styling Issues**: Check CSS variable overrides and custom styles
3. **API Errors**: Verify API endpoints and network connectivity
4. **TypeScript Errors**: Ensure all required props are provided
### Debug Mode
Enable console logging for debugging:
```tsx theme={null}
{
console.log('kelviq Debug:', {
error: error.message,
productId: 'your-product-id',
timestamp: new Date().toISOString()
});
}
}}
>
```
***
## Using the Sandbox
If you want to use the sandbox, you need to set the `environment` option to `sandbox` in the `KelviqProvider`.
```tsx theme={null}
{/* Your app components */}
```
## 12. Support
For technical support and questions:
* **Documentation**: [docs.kelviq.com](https://docs.kelviq.com)
* **Email**: [hi@kelviq.com](mailto:hi@kelviq.com)
***
# Fees
Source: https://docs.kelviq.com/getstarted/fees
Understand Kelviq's transaction fees and additional charges
Kelviq operates as a [Merchant of Record](/getstarted/merchant-of-record), handling payments, tax compliance, and global selling on your behalf. You pay a transaction fee when a payment succeeds. There are no setup fees, monthly fees, or minimum transaction requirements.
## What's included
Your transaction fee covers everything you need to sell globally:
* Payment processing (cards, wallets, local payment methods)
* Sales tax, VAT, and GST calculation, collection, and remittance
* Fraud protection and chargeback handling
* Localized pricing in 135+ currencies
* Compliance with regional regulations
* Usage metering and billing
* License key generation
* Digital product and file delivery
* Feature and entitlement management
* Customer billing portal
## Transaction fees
Every successful payment starts with a base fee. The base rate changes after your organization processes \$5,000 in total sales volume. A recurring charge or international card can add another percentage to the same transaction.
| Fee component | Rate | When it applies |
| - | - | - |
| Base fee, up to \$5,000 in total volume | 2.9% + \$0.40 | Successful transactions processed before your organization reaches \$5,000 in total sales |
| Base fee, after \$5,000 in total volume | 3.5% + \$0.40 | Subsequent successful transactions after your organization reaches \$5,000 in total sales |
| Recurring billing | +0.7% | Subscription payments and renewals |
| International card | +1.5% | Cards issued outside the United States |
> [!NOTE]
>
> The recurring and international-card percentages are added to the applicable base rate. The fixed \$0.40 is charged once per successful transaction.
### How the \$5,000 threshold works
The threshold is based on your organization's cumulative processed sales volume, not the number of payments or the volume for a single month. You pay 2.9% + \$0.40 on transactions processed before reaching \$5,000. After your total processed volume reaches \$5,000, subsequent transactions use the 3.5% + \$0.40 base rate.
The rate change does not alter fees on transactions that were already processed.
## All fee combinations
The additional percentages stack when a charge is both recurring and paid with an international card.
| Transaction type | Up to \$5,000 in total volume | After \$5,000 in total volume |
| - | - | - |
| One-time payment, domestic card | 2.9% + \$0.40 | 3.5% + \$0.40 |
| One-time payment, international card | 4.4% + \$0.40 | 5.0% + \$0.40 |
| Subscription, domestic card | 3.6% + \$0.40 | 4.2% + \$0.40 |
| Subscription, international card | 5.1% + \$0.40 | 5.7% + \$0.40 |
### Example fees on a \$100 charge
This example uses a \$100 gross charge. If the payment includes tax, the gross amount is the full amount charged to the customer.
| Transaction type | Fee before the \$5,000 threshold | Fee after the \$5,000 threshold |
| - | -: | -: |
| One-time payment, domestic card | \$3.30 | \$3.90 |
| One-time payment, international card | \$4.80 | \$5.40 |
| Subscription, domestic card | \$4.00 | \$4.60 |
| Subscription, international card | \$5.50 | \$6.10 |
### Example: a sale with sales tax
A customer in the US buys a \$50 product with a US card. Sales tax is 8%, so they pay \$54. Your organization has already passed \$5,000 in sales, so the base fee is 3.5% + \$0.40. The fee is charged on the full amount the customer pays, including tax.
| | Amount |
| - | -: |
| Customer pays (\$50 + \$4 sales tax) | \$54.00 |
| Kelviq fee (3.5% of \$54 + \$0.40) | −\$2.29 |
| Sales tax, collected and remitted by Kelviq | −\$4.00 |
| **Added to your balance** | **\$47.71** |
| Payout fee | \$0.00 |
Before the \$5,000 threshold, the same sale costs 2.9% + \$0.40, a \$1.97 fee.
## How fees appear in Transactions
The **Fee** column under **Payouts → Transactions** shows the total fee deducted from a payment. It combines the applicable base rate, recurring fee, and international-card fee into one amount. Tax is shown separately.
For a successful transaction:
```text theme={null}
Net = Gross - Fee - Tax
```
[Learn how to read the Transactions page →](/payouts/transactions)
## Payout fees
There's no payout fee. Your full balance is sent to your bank account or eligible debit card. If your bank account uses a different currency, the amount is converted when the payout is sent.
[Learn how Kelviq payouts work →](/payouts/overview)
## Refunds
Here's how a refund of the \$54 sale above is paid out:
| | Full refund | Partial refund of \$20 |
| - | -: | -: |
| Customer gets back | \$54.00 | \$20.00 |
| Tax part of the refund, returned by Kelviq | \$4.00 | \$1.48 |
| Taken from your balance | \$50.00 | \$18.52 |
| **What you keep from the sale** | **−\$2.29** | **\$29.19** |
For a partial refund, the amount you enter is what the customer gets back, and the tax inside it is worked out proportionally (\$20 × \$4 / \$54 = \$1.48).
If your balance is lower than the amount taken for a refund, the refund still goes through and your balance goes negative.
## Disputes and chargebacks
When a customer disputes a charge with their bank, a **\$15 fee** applies regardless of the dispute outcome.
| Outcome | Fee | Transaction amount |
| - | - | - |
| You win | \$15 | Returned to you |
| You lose | \$15 | Refunded to customer |
### Reducing disputes
> **Clear billing descriptors**
>
> Use a recognizable business name on statements so customers remember the purchase.
> **Proactive support**
>
> Make it easy for customers to contact you before they escalate to their bank.
> **Accurate descriptions**
>
> Set clear expectations about what customers are purchasing and delivery timelines.
> **Easy cancellation**
>
> For subscriptions, provide a simple way to cancel to prevent "friendly fraud" disputes.
## FAQ
> **When are fees deducted?**
>
> Fees are deducted automatically from each transaction before the payout reaches your account.
> **Are there monthly fees or minimums?**
>
> No. You only pay when you make a sale. There are no setup fees, monthly fees, or minimum transaction requirements.
> **How is 'international' determined?**
>
> A transaction is considered international when the customer's card is issued outside the United States. Since Kelviq is the Merchant of Record registered in the US, this applies regardless of where your business is located.
> **Do fees apply to free trials?**
>
> No. Fees only apply to successful paid transactions. \$0 trial authorizations do not incur fees.
> **What about failed transactions?**
>
> No fees are charged for declined or failed transactions.
# Introduction to Kelviq
Source: https://docs.kelviq.com/getstarted/introduction-to-kelviq
What Kelviq does, how it fits into your app, and where to start.
Kelviq is a merchant of record with billing built in. You set your prices and plans, Kelviq sells them, collects the tax, and pays you out. Your app asks Kelviq what each customer can use.
> **[Set up with your coding agent](/ai/overview)**
>
> Using Claude Code, Cursor, or Codex? Your agent can set up Kelviq for you.
## What Kelviq handles
| Area | What you get |
| - | - |
| **Tax and compliance** | Kelviq is the seller of record. We calculate, collect, and file sales tax, VAT, and GST, and handle fraud and chargebacks. |
| **Checkout** | Hosted checkout with plan picker, trials, discounts, business purchases, and local payment methods. |
| **Pricing** | Flat, per seat, usage-based, tiered, volume, credits, pay as you go, one-time, or a mix. |
| **Entitlements** | Turn features on per plan, set usage limits, and check what each customer can access with one SDK call. In the dashboard, these are **Features & limits**. |
| **Usage** | Report usage as it happens. Kelviq counts it, resets it, and bills overage. |
| **Subscriptions** | Upgrades, downgrades, proration, and cancellations, plus a customer portal. |
| **Digital products** | File downloads, license keys, and links delivered after purchase. |
| **Local pricing** | Prices by country in 135+ currencies. |
Pricing changes happen in the dashboard or the CLI, not in your code. Your app checks features, not plan names, so moving a feature between plans needs no deploy.
## How it fits together
1. Create **products**, **plans**, and **features** in the dashboard or with the CLI.
2. Send customers to **checkout**. Kelviq takes the payment and the tax.
3. Your app **checks access** and **reports usage** with the SDK.
4. Kelviq bills renewals and overage, and **pays you out**.
## FAQ
> **Do I need to handle webhooks?**
>
> No. Your app can ask Kelviq for a customer's access at any time, so you don't need to keep subscription state in your database. [Webhooks](/guides/webhooks) are there if you want events in your own systems.
> **What if Kelviq can't be reached?**
>
> The Node and Python SDKs return the last known access for a customer and retry usage reports later. See [When the Entitlement API is unavailable](/product-catalog/entitlements#when-the-entitlement-api-is-unavailable).
> **Can I test without real payments?**
>
> Yes. The [sandbox](/guides/sandbox) is a separate environment with its own keys and test cards.
> **What does it cost?**
>
> A percentage of each transaction, with no monthly fee. See [Fees](/getstarted/fees).
> **Do I need a Stripe account?**
>
> No. You can sell and get paid without one, including in countries where Stripe doesn't offer its own accounts, such as India. Payouts go through a payout account you set up in Kelviq. See [Payouts](/payouts/overview#do-i-need-a-stripe-account).
> **Can I use my own Stripe account?**
>
> Yes, if you'd rather stay the merchant of record yourself. You then handle your own tax and compliance. See [Merchant of record](/getstarted/merchant-of-record).
> **[Next: set up your dashboard](/quickstart/dashboard-setup)**
>
> Create a product, a plan, and your first feature.
## Need help?
Email us at **[hi@kelviq.com](mailto:hi@kelviq.com)** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
# Merchant of Record
Source: https://docs.kelviq.com/getstarted/merchant-of-record
Kelviq operates as your Merchant of Record (MoR). This means we are the legal reseller of your products to the end customer. We handle the taxes, compliance, and payment liability so you don’t have to.
***
## What is a Merchant of Record (MoR)?
The "Merchant of Record" is the most important concept to understand when using Kelviq. It's the engine that enables you to sell globally without handling the legal and financial complexity yourself.
A Merchant of Record is the entity that is **legally responsible for selling a product to an end customer**.
When a customer buys your product, their financial transaction is with the MoR (Kelviq), not with your company. We take on the responsibility for that sale, handling all the complex financial and legal requirements that come with it.
This model allows you to focus 100% on building your product while we handle the entire checkout, tax, and compliance backend.
***
### The Core Responsibilities of an MoR
By acting as your MoR, Kelviq takes on a massive amount of financial and legal liability. This is the "hard part" of global sales that we handle for you:
* **Global Tax & Compliance**
This is the single biggest challenge of selling online. An MoR is responsible for calculating, collecting, and remitting sales taxes like VAT (EU and UK), GST (India, Australia, Singapore, New Zealand), GST/HST (Canada), JCT (Japan), and state-level sales tax in the U.S.
* **Financial Liability & Risk**
The MoR is financially liable for every transaction. This includes bearing the cost of customer chargebacks (disputes) and all fraudulent payments.
* **Payment & Regulatory Burden**
The MoR ensures that every part of the checkout and payment process is compliant with global regulations, such as PCI-DSS and PSD2/SCA.
### How it Works: A Real-World Example
To understand exactly where the money goes, let's look at a specific transaction.
1. **The Sale:** A customer in **Germany** visits your site and buys your product. You have set the price at **€50.00**.
2. **The Calculation:** Kelviq automatically detects the customer is in Germany and adds the 19% German VAT (€9.50). The customer pays a total of **€59.50**.
3. **The Legal Transaction:** The customer's €59.50 transaction is legally with Kelviq. We are the "seller" on their invoice.
4. **Tax Remittance (The Hard Part):** At the end of the quarter, our finance team takes that **€9.50** and files the VAT return with the German authorities. You never see or touch this tax money, so you never have to worry about it.
5. **Your Payout:** We take our fee from the full **€59.50** the customer paid, send the €9.50 VAT to the German tax authority, and pay the rest out to your bank account. See [Fees](/getstarted/fees).
You get your expected revenue. We handle the legal and tax complexity of the extra €9.50.
### MoR vs. Payment Service Provider (PSP)
A PSP (like Stripe or PayPal) gives you the *tools* to process a payment, but **you** are still the seller of record.
| Feature | Payment Service Provider (PSP) | Merchant of Record (Kelviq) |
| :- | :- | :- |
| **Who is the Seller?** | **You** are the seller of record. | **Kelviq** is the seller of record. |
| **Tax Liability** | **Your responsibility.** You must register, file, and remit. | **Kelviq's responsibility.** We handle all filing and payments. |
| **Fraud Risk** | **You.** You lose the sale + fees on chargebacks. | **Kelviq.** We take the financial hit. |
| **Time to Market** | Weeks or months of setup. | Minutes. |
### Your Two Model Choices in Kelviq
Kelviq is designed to be flexible, offering two primary ways to operate:
**1. Kelviq as your Merchant of Record (Recommended)**
This is the default and recommended model. When you sign up, Kelviq acts as your MoR, handling all the responsibilities described on this page. You get the full all-in-one platform with zero compliance overhead.
**2. Bring Your Own Stripe Account (BYOA)**
For businesses that prefer to remain the Merchant of Record, you can connect your own Stripe account. In this model, **you are responsible for your own tax, fraud, and compliance**, but you still get access to all of Kelviq's monetization features—such as our usage-based pricing engine, feature flagging, and localization tools. Please contact us at [hi@kelviq.com](mailto:hi@kelviq.com) to enable this option.
# Payment security and seller funds
Source: https://docs.kelviq.com/getstarted/payment-security-and-seller-funds
How Kelviq protects card details, routes payments through Stripe, and handles payouts, account reviews, and migrations
When a customer buys through Kelviq Checkout, Kelviq is the Merchant of Record and Stripe processes the payment. The customer's raw card details go directly to Stripe through secure payment fields; they are not passed to Kelviq or your connected account. Stripe also provides the connected account used for your payouts. Here is how payment data, money, and subscription records move at each stage.
> [!NOTE]
>
> This page is an operational overview. If it conflicts with the [Seller Agreement](/legal/master-service-agreement), the agreement controls.
## How does a payment move?
**1. The customer enters their payment details**
Kelviq Checkout uses [Stripe Elements](https://docs.stripe.com/payments/elements). Stripe tokenizes sensitive payment details in the browser, so the full card number and CVC do not pass through or get stored on Kelviq's servers.
**2. Stripe processes the charge**
The charge and its PaymentIntent are created on Kelviq's Stripe platform account because Kelviq is the Merchant of Record.
**3. Kelviq calculates your share**
Kelviq accounts for applicable taxes, platform fees, refunds, and other adjustments before calculating your net revenue.
**4. Your revenue moves to your connected account**
Kelviq creates a separate transfer to your Stripe Express connected account. The funds appear there after Stripe makes them available.
**5. Stripe pays your bank account**
You can withdraw cleared funds to the bank account attached to your connected account.
> [!NOTE]
>
> Kelviq uses Stripe Connect's **separate charges and transfers** model. It does not use direct charges or destination charges. See the [full payment flow](/legal/payment-flow-diagram) for the technical breakdown.
## Who handles the card details?
The checkout may carry Kelviq's design, but Stripe provides the sensitive payment fields. Stripe.js tokenizes the details inside those fields and returns identifiers Kelviq can use to complete the payment. Kelviq receives the payment result, not the customer's full card number or CVC.
Stripe can also request 3D Secure authentication when it is required by the card issuer or recommended for fraud prevention. This adds an identity check without exposing the customer's card details to Kelviq.
Banks can still decline or reverse a payment, customers can open disputes, and Stripe or a card network can request a review. Kelviq handles those events as the Merchant of Record.
## Where does the money actually sit?
During processing, the money appears in Stripe balances. It first appears in Kelviq's Stripe platform balance. After the separate transfer, your share appears in your Stripe connected-account balance. Stripe then sends the payout to your registered bank account.
A Kelviq payout balance is not a bank deposit, escrow account, or insured investment. It represents amounts due under the Seller Agreement and can change because of refunds, chargebacks, fees, currency conversion, or a valid reserve.
You can track this flow in two places:
* The Kelviq **Payouts** dashboard shows processing funds, cleared funds, withdrawals, and payout history.
* Your Stripe connected-account details show the verified business and bank account used for payouts.
Read [Payouts](/payouts/overview) for the dashboard workflow.
## What protects my funds if Kelviq closes my account?
The Seller Agreement sets out Kelviq's payout obligations and when a payout can be delayed or reserved:
* Completed transactions move to your available balance after processing.
* Final payouts remain due if Kelviq ends the service, subject to open disputes and a permitted reserve.
* A reserve must have a stated amount or percentage and an expected duration.
* A post-termination reserve can remain in place for up to 180 days to cover refunds, chargebacks, or other transaction liabilities.
This is not a guarantee that nothing can go wrong. A processor failure, bank delay, dispute, compliance action, or insolvency can still affect the timing or recovery of funds. What you do have is a written payment flow, transaction records, and contractual payout terms against which you can check Kelviq's handling of your money. Review [Payout Terms](/legal/master-service-agreement#7-payout-terms) and [Reserves and Holdbacks](/legal/master-service-agreement#8-reserves-and-holdbacks) for the controlling language.
## How much notice will I get before a suspension?
There is no single advance-notice period for every suspension, including every non-fraud suspension. Kelviq may need to act quickly because of suspected fraud, prohibited activity, failed verification, a legal requirement, a payment-network instruction, or a restriction on the connected Stripe account.
The 30-day notice in the Seller Agreement applies when Kelviq terminates an account for convenience. It does not apply to the grounds for immediate termination listed in that agreement. If you believe a policy suspension or termination was made in error, you can appeal it. Kelviq responds to appeals within 10 business days under the [Acceptable Use Policy](/legal/approved-prohibited-policy#83-appeal-process).
### Will my customers' subscriptions cancel immediately?
Not in every case. A suspension and a subscription cancellation are separate actions. However, Kelviq may need to block checkout or future renewals, depending on why the account was restricted. The Seller Agreement does not promise uninterrupted subscription collection during a suspension. If a notice does not clearly say which functions are affected, contact [support@kelviq.com](mailto:support@kelviq.com) before making changes for your customers.
## Where do the Stripe Customer and Subscription records live?
Kelviq manages the buyer-facing Stripe Customer, PaymentIntent, invoice, and Subscription records on its Stripe platform account. Your Stripe Express connected account receives transfers and payouts; it does not receive an independent copy of every platform billing object.
An ID such as `cus_...` or `sub_...` points to an object inside the Stripe account where it was created. It cannot simply be reassigned to another Stripe account. Under the [Seller Agreement](/legal/master-service-agreement#111-buyer-data), Kelviq controls buyer payment and transaction data in its role as Merchant of Record. You still own your product and content, and Kelviq provides the buyer information needed for fulfillment and customer support.
## Can I move to another provider?
A billing migration is possible in some cases, but it is not an automatic account transfer. Contact [support@kelviq.com](mailto:support@kelviq.com) before closing your Kelviq account or disconnecting Stripe. Kelviq will review the request with Stripe and the receiving provider, then explain what can be transferred.
Stripe supports secure exports of eligible card data to a PCI DSS Level 1 payment processor. Some credentials, including cards saved through Link, cannot be exported. Subscription records and payment history also need to be mapped or recreated in the new billing system; moving card data alone does not move an active subscription.
Migration scope and timing depend on the receiving provider, Stripe's requirements, applicable privacy rules, and any unresolved refunds, disputes, or reserves. See [Stripe's payment-data export process](https://docs.stripe.com/get-started/data-migrations/pan-export) for the processor-level requirements.
## Questions about your account
For an account-specific explanation of a payout, reserve, suspension, or migration, email [support@kelviq.com](mailto:support@kelviq.com). Include your Kelviq business name and the relevant transaction, payout, or subscription IDs, but never send a full card number or CVC.
# Review Process
Source: https://docs.kelviq.com/getstarted/review-process
Because Kelviq operates as your **Merchant of Record (MOR)**, we are legally and financially responsible for every transaction processed through our platform. To ensure the safety of the ecosystem and comply with global financial regulations, we must strictly review the businesses we support.
This guide outlines what we support, what we prohibit, and how our review process works.
## 1. Supported Business Models
Kelviq is optimized for **digital products and software**. We are the best fit for:
* **SaaS & Software:** B2B or B2C web applications, desktop software, AI tools, and browser extensions.
* **Digital Downloads:** E-books, PDFs, design templates, audio files, video courses, and fonts.
* **Membership Sites:** Newsletters, research communities, and gated content.
* **Professional Services:** *Only if sold alongside a software product (e.g., "Setup Fee" or "Priority Support").*
> **The Golden Rule:**
> Your product should be **digital**, **owned by you** (or properly licensed), and **deliverable immediately** upon purchase.
### ⛔ The Three Fundamental Limitations
Before proceeding, please note the three "Hard No" rules of our MOR service:
1. **Digital Only:** We cannot support physical goods, shipping, or logistics.
2. **No Manual Services:** We cannot support 1-on-1 coaching, consulting, or agencies where the primary value is your manual labor.
3. **No Marketplaces:** You must be the original creator or licensed distributor. You cannot use Kelviq to process payments for other unverified sellers.
## 2. Global Compliance & High-Risk Categories (Prohibited)
We are required by law and our financial partners to block any product or service that is illegal, deceptive, or creates a high financial risk.
This list is not exhaustive, and we reserve the right to review, suspend, or terminate any account that we believe violates the spirit of these rules.
### A. Illegal, Deceptive, or Hateful Content
* Any product or service that is illegal in the U.S. or your customer's location.
* Content that infringes on someone else's Intellectual Property (IP), copyright, or trademark. (e.g., pirated software, stolen ebooks, cracked license keys).
* Hate speech or content that promotes violence, self-harm, or discrimination against any group.
* Deceptive marketing practices, fake testimonials, or unrealistic "get rich quick" schemes.
* Low-value, exploitative content (e.g., rapidly AI-generated ebooks with minimal substance sold at a high price).
* Identity services, fake IDs, or products that support academic cheating.
### B. Financial and Legal Services
* **Regulated Financial Products:** We cannot sell investment advice, trading signals, cryptocurrency, NFTs, lending services, or act as a money transmitter.
* **Gambling:** All forms of gambling, betting, or games of chance.
* **Regulated Professional Services:** We cannot sell legal, tax, or accounting advice.
* **Donations:** We cannot process donations where no specific product is delivered.
* **Regulatory Evasion:** Any service designed to help others evade taxes, mask their identity, or bypass financial regulations.
### C. Adult & Regulated Industries
* **Adult Content:** Explicitly sexual content (videos, images, text), whether real or **AI-generated**. This includes "AI Girlfriend/Boyfriend" services, NSFW chatbots, and services related to OnlyFans.
* **Controlled Substances:** Alcohol, tobacco, vaping products, drugs, or drug paraphernalia.
* **Weapons:** Firearms, ammunition, explosives, or combat training.
* **Pharmaceuticals:** Prescription drugs or unverified medical/wellness supplements.
### D. Platform & Technology Abuse
* **Spam & Scraping:** Tools for mass cold emailing, lead scraping, or sending bulk SMS/WhatsApp messages.
* **Hacking & Cheating:** Tools designed to cheat in games, bypass software rules, or gain unauthorized access.
* **Circumvention Tools:** Services that bypass API limits, platform rules, or geo-restrictions (e.g., IP cloaking).
* **Surveillance Tech:** Products that violate user privacy or enable unauthorized surveillance (e.g., keyloggers, stalkerware).
## 3. Restricted Businesses (Requires Extensive Review)
The following businesses are not automatically prohibited, but they are considered high-risk and require extensive review by our compliance team. Approval is not guaranteed and may be subject to additional conditions (like holding funds in reserve).
* **AI-Powered Services:** Especially tools for AI-generated text, images, or voice. We need to review your product to ensure it has proper safeguards against generating harmful, deceptive, or adult content.
* **Marketing Services:** Some marketing tools may be allowed, but we must review them to ensure they do not facilitate spam or mass outreach.
* **Pre-Orders & Paid Waitlists:** We generally **do not** allow pre-orders. This is a very high-risk category for an MOR. In rare cases, we may make an exception for established creators, but funds will be withheld until the product is verifiably shipped.
## 4. Prohibited & Supported Countries
### Prohibited Countries
As a U.S. company, Kelviq is required to comply with U.S. sanctions laws (OFAC). We are **strictly prohibited** from doing business with any individual or entity located in:
* North Korea
* Iran
* Cuba
* Syria
* Russia
* Belarus
* The regions of Crimea, Donetsk, and Luhansk
### Supported Payout Countries
We support businesses registered in **100+ countries**. You can receive payouts in your local bank account in currencies including USD, EUR, GBP, CAD, AUD, INR, and more.
| | | |
| :- | :- | :- |
| 🇦🇱 Albania | 🇦🇬 Antigua & Barbuda | 🇦🇷 Argentina |
| 🇦🇲 Armenia | 🇦🇺 Australia | 🇦🇹 Austria |
| 🇧🇸 Bahamas | 🇧🇭 Bahrain | 🇧🇪 Belgium |
| 🇧🇯 Benin | 🇧🇴 Bolivia | 🇧🇦 Bosnia & Herzegovina |
| 🇧🇼 Botswana | 🇧🇳 Brunei | 🇧🇬 Bulgaria |
| 🇰🇭 Cambodia | 🇨🇦 Canada | 🇨🇱 Chile |
| 🇨🇴 Colombia | 🇨🇷 Costa Rica | 🇨🇮 Côte d'Ivoire |
| 🇨🇾 Cyprus | 🇨🇿 Czech Republic | 🇩🇰 Denmark |
| 🇩🇴 Dominican Republic | 🇪🇨 Ecuador | 🇪🇬 Egypt |
| 🇸🇻 El Salvador | 🇪🇪 Estonia | 🇪🇹 Ethiopia |
| 🇫🇮 Finland | 🇫🇷 France | 🇬🇲 Gambia |
| 🇩🇪 Germany | 🇬🇭 Ghana | 🇬🇷 Greece |
| 🇬🇹 Guatemala | 🇬🇾 Guyana | 🇭🇰 Hong Kong |
| 🇭🇺 Hungary | 🇮🇳 India | 🇮🇸 Iceland |
| 🇮🇪 Ireland | 🇮🇱 Israel | 🇮🇹 Italy |
| 🇯🇲 Jamaica | 🇯🇵 Japan | 🇯🇴 Jordan |
| 🇰🇪 Kenya | 🇰🇼 Kuwait | 🇱🇻 Latvia |
| 🇱🇹 Lithuania | 🇱🇺 Luxembourg | 🇲🇴 Macao SAR China |
| 🇲🇬 Madagascar | 🇲🇹 Malta | 🇲🇺 Mauritius |
| 🇲🇽 Mexico | 🇲🇩 Moldova | 🇲🇨 Monaco |
| 🇲🇳 Mongolia | 🇲🇦 Morocco | 🇳🇦 Namibia |
| 🇳🇱 Netherlands | 🇳🇿 New Zealand | 🇳🇬 Nigeria |
| 🇲🇰 North Macedonia | 🇳🇴 Norway | 🇴🇲 Oman |
| 🇵🇰 Pakistan | 🇵🇦 Panama | 🇵🇾 Paraguay |
| 🇵🇪 Peru | 🇵🇭 Philippines | 🇵🇱 Poland |
| 🇵🇹 Portugal | 🇶🇦 Qatar | 🇷🇴 Romania |
| 🇷🇼 Rwanda | 🇸🇦 Saudi Arabia | 🇸🇳 Senegal |
| 🇷🇸 Serbia | 🇸🇬 Singapore | 🇸🇰 Slovakia |
| 🇸🇮 Slovenia | 🇿🇦 South Africa | 🇰🇷 South Korea |
| 🇪🇸 Spain | 🇱🇰 Sri Lanka | 🇱🇨 St. Lucia |
| 🇸🇪 Sweden | 🇨🇭 Switzerland | 🇹🇼 Taiwan |
| 🇹🇿 Tanzania | 🇹🇭 Thailand | 🇹🇹 Trinidad & Tobago |
| 🇹🇳 Tunisia | 🇹🇷 Turkey | 🇦🇪 United Arab Emirates |
| 🇬🇧 United Kingdom | 🇺🇸 United States | 🇺🇾 Uruguay |
| 🇺🇿 Uzbekistan | 🇻🇳 Vietnam | |
*This list is determined by our payment provider and is subject to change. If your country is not listed here, you will not be able to complete onboarding or receive payouts.*
## 5. The Review Process
Before you can process real payments, your account must pass our verification process. You can integrate and test in "Sandbox Mode" immediately, but "Live Mode" requires approval.
There are two steps to complete before you can start accepting real payments:
### Step 1: Business Verification
Open **Settings → Business details** in the Kelviq dashboard.
Fill in your business details: logo, country, website, a support email that buyers will see, a short overview of what you sell, your estimated monthly revenue, and your social profiles. Kelviq places the country from your organization profile first in the country selector. Check it before you save.
Click **Save details**. The page then shows that your details are under review, and you can carry on creating products and testing in sandbox while you wait.
**What happens next:**
* Most reviews are completed within **24 hours**.
* If we need more information, we'll reach out to you via email.
* Once your verification is approved, you'll receive a confirmation email.
### Step 2: Set Up Payouts
After your business is verified, you need to set up payouts to receive money from your sales. We partner with **Stripe** to enable secure payouts.
Navigate to the **Payouts** section in your dashboard, or go directly to [app.kelviq.com/payout](https://app.kelviq.com/payout).
Click the **Set up payouts** button. You'll be redirected to Stripe to complete a quick setup:
1. **Verify your identity** - Stripe will ask for a few details to verify your identity and business.
2. **Connect your bank account** - Add your bank account details to receive payouts.
Once you complete the Stripe setup, you'll be redirected back to Kelviq.
### You're Ready to Go Live
Once both steps are completed (Business Verification and Payout Setup), you can start accepting real payments from customers.
## 6. Testing Payments
> [!WARNING]
>
> Do not use your own real card to test payment flows.
For testing, you have two options:
1. **Use Sandbox Mode** - Switch to sandbox mode in your dashboard to test the entire checkout flow with test card numbers.
2. **Use 100% Discount Coupons** - Create a discount coupon with 100% off to test the checkout workflow in live mode without being charged.
## 7. Enforcement & Monitoring
Once you are live, we continuously monitor account activity to prevent fraud and ensure ongoing compliance.
* **Refund Rate Monitoring:** If your refund rate exceeds acceptable thresholds (typically >10%), we may reach out to help you improve your product quality or support.
* **Chargeback Monitoring:** We maintain a strict low-tolerance policy for chargebacks. Excessive dispute levels may result in account review.
* **Prohibited Activity:** If an account is found to be selling prohibited items or engaging in money laundering/fraud after approval, the account will be suspended immediately and funds may be held to cover potential disputes.
## 8. Have a Question About Your Product?
We know this list is long, and the line can be blurry, especially with new AI tools. We want to support innovative products.
If you are unsure if your product is allowed, **please contact us at [hi@kelviq.com](mailto:hi@kelviq.com) *before* you launch.**
Our simple "gut check" is: **Is this a high-quality, legitimate product that you are proud of, that you own the rights to, and that is delivered digitally?** If you can answer "yes" to all three, you are probably in the clear.
# Agent Toolkit
Source: https://docs.kelviq.com/guides/agent-toolkit
Install Kelviq into Claude Code with one plugin — or add the Kelviq skills to any of 70+ AI coding agents.
The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus five **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
Skills are the missing half of tool access. The MCP server gives your agent 57 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
> [!NOTE]
>
> **The Agent Toolkit is new.** The skills and their names are stable, but content will keep improving alongside the platform. The bundled MCP server is always the latest published `@kelviq/mcp-server` — no toolkit update needed when the server improves.
***
## Install — Claude Code
Two commands, in any Claude Code session:
```
/plugin marketplace add kelviq/agent-toolkit
/plugin install kelviq@kelviq
```
This installs the full bundle: the MCP server is configured for you (no `claude mcp add`, no `--` separator gotchas) and all five skills are available immediately.
The server reads your API keys from environment variables. It uses your **sandbox** environment unless `KELVIQ_ENV=production`, so start with sandbox keys. Set them in your shell profile before starting Claude Code:
```bash theme={null}
export KELVIQ_SERVER_API_KEY=""
export KELVIQ_CLIENT_API_KEY="" # only needed for promotion_get
```
Get keys at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
**Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 57 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
> [!TIP]
>
> No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work without any credentials, so your agent can answer Kelviq questions from the documentation immediately. API tools return a clear `Configuration error` until a key is set.
***
## Install — any other agent
The five skills are also published through the open skills ecosystem, installable into 70+ agents (Cursor, Codex, GitHub Copilot, OpenCode, Zed, and more):
```bash theme={null}
npx skills add kelviq/agent-toolkit
```
Add `--skill ` to install a single skill instead of the full set:
```bash theme={null}
npx skills add kelviq/agent-toolkit --skill setup-payments
```
> [!NOTE]
>
> This path installs **skills only** — it doesn't configure an MCP server for you. Each skill starts with a short Setup section showing the `.mcp.json` snippet to connect `@kelviq/mcp-server` on your agent; see the [MCP server guide](/guides/mcp-server) for client-specific instructions.
***
## The five skills
| Skill | What it teaches |
| - | - |
| `kelviq` | The hub. Connecting any agent to Kelviq, the ground rules (docs-first, error handling, confirm-before-destructive), the concept model (identifiers vs UUIDs, feature types, plan lifecycle, environments), and routing to the right skill or prompt for the task. |
| `pricing-plans` | Designing and publishing the catalog: products, features, plans, entitlements, the DRAFT → publish lifecycle, and customer-migration decisions on publish. |
| `setup-payments` | Selling plans and managing subscribers: checkout sessions, subscriptions, trials, upgrades, cancellation, and authenticated customer portal links. |
| `usage-based-billing` | Enforcing what was sold: runtime entitlement checks served from the edge, safe usage reporting for Meter features, and the license key lifecycle. |
| `pricing-as-code` | The [Kelviq CLI](/cli/overview) workflow: pull the live catalog into `kelviq.config.ts`, edit in git, preview the diff, apply, and promote sandbox to production. |
### `kelviq` — the hub
Loads for any Kelviq task that doesn't match a more specific skill. It carries the knowledge every other skill assumes:
* **Identifiers vs UUIDs** — when an endpoint wants the URL-safe `identifier` and when it wants the UUID, and how to resolve one from the other.
* **Feature types** — `BOOLEAN` (flag), `CUSTOMIZABLE` (numeric quantity), `METER` (usage-tracked), and how entitlement shapes differ per type.
* **Plan lifecycle** — plans are created in DRAFT and invisible until published; updating a published plan creates a new draft.
* **Environments** — sandbox by default, `KELVIQ_ENV=production` only for live data, and why "not found" errors often mean "right key, wrong environment".
* **A customer-access diagnosis flow** — comparing what a customer *has* (`entitlements_get`), what they *bought* (`subscription_list`), and what their plan *grants* (`plan_entitlements_list`).
### `pricing-plans`
The golden path from empty account to published plan: create the product, create the features, create the plan (in DRAFT), attach entitlements, set prices, publish, verify. Includes the two decisions agents most often get wrong: whether to migrate existing customers on publish (`updateFeatures` / `updatePricing` — always a deliberate, confirmed choice), and where prices are managed (the dashboard or the CLI — the MCP server deliberately has no price-write tool).
### `setup-payments`
Checkout-first selling. The skill teaches that `checkout_create_session` is the default way to charge a customer — direct subscription creation charges off-session and is only enabled for some organizations — plus trial handling (`trialEnd`), safe plan changes (`paymentBehavior`), cancellation types, and the customer portal (always the signed URL from `portal_session_create`; a bare portal URL doesn't authenticate).
### `usage-based-billing`
Runtime enforcement. Entitlement checks via the edge-served `entitlements_get` (built to be cheap enough to call on the request path), the difference between `SET` and `DELTA` usage reporting — and why a blindly retried `DELTA` double-counts — plus license key activation, validation, and deactivation with `instanceId` handling.
### `pricing-as-code`
Wraps the [Kelviq CLI](/cli/overview) loop for agents: `kelviq pull` → edit `kelviq.config.ts` in a branch → `kelviq push --dry-run` → review → apply → `kelviq promote` from sandbox to production. The skill has a built-in safety rule: an agent may run dry-runs and show you diffs freely, but **applying a real change always requires your explicit approval** — it will never chain a dry-run into an unattended `--yes`.
***
## Skills, prompts, and tools — how they fit
The toolkit layers three things, each doing what it's best at:
1. **Tools** (from the MCP server) do the work — 57 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
2. **Skills** (from this toolkit) supply the judgment — which tool, in what order, with which confirmations. They activate automatically based on what you ask.
3. **Prompts** (from the MCP server) are guided, step-by-step flows you invoke explicitly — `setup_product`, `launch_plan`, and `diagnose_customer`. The skills route to them rather than duplicating them.
Deep reference detail (field lists, price shapes, config schemas) intentionally lives in none of these — the skills direct the agent to `docs_search` / `docs_read`, so answers always come from the current documentation.
***
## Sandbox and production
The bundled server uses your **sandbox** environment unless you set `KELVIQ_ENV=production` — separate data, separate keys, nothing crosses between them. Build and test in sandbox, and switch to production (with production API keys) only when you want the agent to work with live data. See the [sandbox guide](/guides/sandbox) for details.
```bash theme={null}
export KELVIQ_ENV="production"
export KELVIQ_SERVER_API_KEY=""
```
***
## Updating
* **MCP server**: nothing to do. The toolkit runs `npx -y @kelviq/mcp-server@latest`, which checks for the newest published version each time the server starts.
* **Skills** (Claude Code): `/plugin marketplace update kelviq` pulls the latest marketplace content.
* **Skills** (other agents): re-run `npx skills add kelviq/agent-toolkit`.
***
## Troubleshooting
**`kelviq:` tools aren't available** — on Claude Code, check `/mcp`; if the server isn't listed, reinstall the plugin. On other agents, the skills-only install doesn't include the server — follow the Setup section in any installed skill or the [MCP server guide](/guides/mcp-server).
**`Configuration error` from API tools** — `KELVIQ_SERVER_API_KEY` isn't visible to the process that launched your agent. Set it in your shell profile (not just the current terminal) and restart the agent.
**"Not found" on an identifier you can see in the dashboard** — your key and `KELVIQ_ENV` are probably pointing at the other environment. Sandbox and production are fully separate; a key only works against its own environment.
***
## Related
* [MCP server guide](/guides/mcp-server) — manual per-client setup, full tool list, architecture
* [Kelviq CLI](/cli/overview) — the pricing-as-code workflow the `pricing-as-code` skill teaches
* [Sandbox](/guides/sandbox) — test environment setup
* [github.com/kelviq/agent-toolkit](https://github.com/kelviq/agent-toolkit) — the toolkit source
# MCP Server
Source: https://docs.kelviq.com/guides/mcp-server
Control Kelviq from Claude, Cursor, and any AI assistant that speaks the Model Context Protocol.
`@kelviq/mcp-server` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for Kelviq. It plugs into any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Devin Desktop (formerly Windsurf), VS Code, Antigravity — and exposes the full Kelviq API as **typed tools** that the LLM can call directly, plus the entire Kelviq documentation as **searchable resources**.
Instead of asking your assistant to "write me a curl command," you describe the outcome ("create a Pro plan under product X and publish it") and it does the work in a single turn.
> [!TIP]
>
> **Using Claude Code?** The fastest install is the [Agent Toolkit](/guides/agent-toolkit) plugin — two commands set up this MCP server *and* five Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.
> [!NOTE]
>
> **57 tools** spanning connection checks, customers, checkout, subscriptions, discounts, webhooks, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and the full OpenAPI spec, and **3 guided prompts** for the most common workflows. Every tool carries [MCP safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
***
## How It Works
The server runs locally on your machine as a Node process started by your AI client. It speaks the MCP **stdio transport** — your client launches `npx -y @kelviq/mcp-server@latest`, connects over stdio, and discovers the tools and resources advertised by the server.
When the LLM decides to call a Kelviq tool, the server:
1. Validates the LLM-provided arguments against the tool's Zod schema.
2. Adds your API key as a Bearer token and sends the HTTPS request to the appropriate Kelviq host.
3. Returns the JSON response (or a structured `{"error": {...}}` object) back to the LLM.
API errors are returned as content, not exceptions — the LLM reads them and reacts (retries with a fix, asks you to clarify, etc).
***
## Step 1: Get Your API Keys
1. Sign in at [app.kelviq.com](https://app.kelviq.com).
2. Navigate to **Settings → API keys**.
3. Copy:
* **Server API Key** — required for all API tools.
* **Client API Key** — required only for the `promotion_get` tool.
> [!WARNING]
>
> Never commit API keys to version control or paste them into shared chats. Use your MCP client's `env` configuration mechanism — most clients store secrets in their own credentials file.
***
## Step 2: Add the Server to Your AI Client
Every client uses the same underlying command — `npx -y @kelviq/mcp-server@latest` — with your API keys and `KELVIQ_ENV` passed as environment variables. What differs is the config file location and, in a few cases, the root JSON key. Pick the tab for your client.
> [!NOTE]
>
> The server uses your **sandbox** environment unless `KELVIQ_ENV=production`. Use keys from the same environment — to work with live data, use production keys and set `KELVIQ_ENV=production`.
**Claude Code**
```bash theme={null}
claude mcp add kelviq \
--env KELVIQ_SERVER_API_KEY= \
--env KELVIQ_CLIENT_API_KEY= \
--env KELVIQ_ENV=sandbox \
-- npx -y @kelviq/mcp-server@latest
```
> [!NOTE]
>
> The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 57 tools`.
**Claude Desktop**
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
```json theme={null}
{
"mcpServers": {
"kelviq": {
"command": "npx",
"args": ["-y", "@kelviq/mcp-server@latest"],
"env": {
"KELVIQ_SERVER_API_KEY": "server-...",
"KELVIQ_CLIENT_API_KEY": "client-...",
"KELVIQ_ENV": "sandbox"
}
}
}
}
```
Restart Claude Desktop — the hammer icon shows `kelviq` with all tools.
**Cursor**
Open **Cursor Settings → Tools and MCP → Add new MCP server**, or edit `.cursor/mcp.json` (project) / `~/.cursor/mcp.json` (global) directly:
```json theme={null}
{
"mcpServers": {
"kelviq": {
"command": "npx",
"args": ["-y", "@kelviq/mcp-server@latest"],
"env": {
"KELVIQ_SERVER_API_KEY": "server-...",
"KELVIQ_CLIENT_API_KEY": "client-...",
"KELVIQ_ENV": "sandbox"
}
}
}
}
```
Project-level config overrides global config when a server of the same name exists in both.
**Windsurf / Devin Desktop**
As of June 2026, Windsurf was rebranded **Devin Desktop** by Cognition. Existing installs update automatically — same editor, new name. The MCP config location also changed with the rebrand:
* **Devin Desktop (current):** `%APPDATA%\devin\config.json` (Windows) — via **Settings → Devin Local → Configuration → MCP servers**
* **Legacy Windsurf installs:** `~/.codeium/windsurf/mcp_config.json`
Add Kelviq under the `mcpServers` key:
```json theme={null}
{
"mcpServers": {
"kelviq": {
"command": "npx",
"args": ["-y", "@kelviq/mcp-server@latest"],
"env": {
"KELVIQ_SERVER_API_KEY": "server-...",
"KELVIQ_CLIENT_API_KEY": "client-...",
"KELVIQ_ENV": "sandbox"
}
}
}
}
```
Save, then refresh or restart the app — `kelviq` should appear under **MCP servers** in Settings, where you can enable it and toggle individual tools.
> [!NOTE]
>
> If your `config.json` isn't empty, check its existing top-level structure before pasting — merge `kelviq` alongside whatever's already there rather than overwriting the file.
**VS Code (Copilot)**
Add a `.vscode/mcp.json` in your workspace, or run **"MCP: Open User Configuration"** from the Command Palette for a global `mcp.json`. VS Code uses `servers`, not `mcpServers`, as the root key:
```json theme={null}
{
"servers": {
"kelviq": {
"command": "npx",
"args": ["-y", "@kelviq/mcp-server@latest"],
"env": {
"KELVIQ_SERVER_API_KEY": "server-...",
"KELVIQ_CLIENT_API_KEY": "client-...",
"KELVIQ_ENV": "sandbox"
}
}
}
}
```
Save, then click the **Start** CodeLens above the `kelviq` entry (or reload the window) and confirm it under the tools icon in Copilot Chat's Agent mode.
> [!TIP]
>
> Already have Kelviq configured in Cursor or Devin Desktop (formerly Windsurf)? Under **Settings → Chat → MCP → Discovery**, check the matching box (e.g. "Windsurf configurations") to auto-import that server instead of retyping it. You can also use the `inputs` array to be prompted for the keys instead of storing them in plaintext.
**Antigravity**
Open the "..." menu in the Agent panel → **MCP Servers** → **Manage MCP Servers** → **View raw config**. This opens `mcp_config.json` at:
* **Windows:** `C:\Users\\.gemini\antigravity\mcp_config.json`
* **macOS/Linux:** `~/.gemini/antigravity/mcp_config.json`
```json theme={null}
{
"mcpServers": {
"kelviq": {
"command": "npx",
"args": ["-y", "@kelviq/mcp-server@latest"],
"env": {
"KELVIQ_SERVER_API_KEY": "server-...",
"KELVIQ_CLIENT_API_KEY": "client-...",
"KELVIQ_ENV": "sandbox"
}
}
}
}
```
> [!NOTE]
>
> The Antigravity **CLI** (as opposed to the IDE) uses a separate config path: `~/.gemini/antigravity-cli/mcp_config.json`.
**Other Clients**
Any client supporting stdio MCP servers works. Point it at:
```bash theme={null}
npx -y @kelviq/mcp-server@latest
```
with the env vars listed below.
***
## Step 3: Try It
In a new session, type a prompt like:
> *Search Kelviq docs for license keys.*
or
> *List my Kelviq products.*
Your AI client should pick the right tool, call it, and show the result inline. If you see a `Configuration error`, your env vars didn't make it through — re-check the config above.
***
## Environment Variables
| Variable | Required | Default | Purpose |
| - | - | - | - |
| `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Server API key (Bearer token for the core API) |
| `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Client API key (Bearer token for the edge host) |
| `KELVIQ_ENV` | No | `sandbox` | `sandbox` or `production`. Set to `production` to work with live data — switches both API hosts automatically. Use a key from the same environment: keys only work against their own environment. |
| `KELVIQ_BASE_URL` | No | per `KELVIQ_ENV` | Advanced: override the core API host |
| `KELVIQ_EDGE_URL` | No | per `KELVIQ_ENV` | Advanced: override the edge host (entitlements + promotions) |
> [!TIP]
>
> Docs tools (`docs_search`, `docs_read`) work with no API keys at all. Even without a key, the LLM can answer Kelviq questions from the bundled documentation.
***
## Tool Reference
Tools are grouped by domain. Each tool name uses `domain_action` form (`customer_create`, `plan_publish`). The LLM picks the right tool from the description automatically — you rarely need to name a tool explicitly.
Wherever a tool takes a product or feature reference (`plan_create`, `plan_entitlements_add`, `discount_create`'s `appliesTo`, `offering_get_product`), it accepts the identifier or the UUID; the server resolves an identifier before calling the API.
### Connection
| Tool | Description |
| - | - |
| `connection_check` | One authenticated read with the server key. Returns the environment, both API hosts and whether the key is `ok`, `missing`, `rejected` or errored, never the key itself. The first thing to call when something returns 401/403. |
### Customers
| Tool | Description |
| - | - |
| `customer_create` | Create a customer. Required: `customerId`. Optional: `email`, `name`, `metadata`, `billingAddress`. |
| `customer_update` | Patch an existing customer by `customerId`. Only fields you pass are updated. |
### Checkout & Portal
| Tool | Description |
| - | - |
| `checkout_create_session` | Create a hosted checkout session. Returns `checkoutUrl` + `checkoutSessionId`. |
| `portal_session_create` | Create a customer portal session. Share the returned `signedPortalUrl` with the customer — the bare `customerPortalUrl` does not authenticate on its own. |
### Subscriptions
| Tool | Description |
| - | - |
| `subscription_create` | Create a subscription directly (skip checkout). Requires off-session charging to be enabled for your organization — otherwise use `checkout_create_session`. |
| `subscription_list` | List subscriptions, filter by customer, paginated. |
| `subscription_update` | Change plan / charge period / features. Free plans must use `checkout_create_session` to upgrade. |
| `subscription_cancel` | Cancel `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, or `SPECIFIC_DATE`. |
### Entitlements, Licenses, Usage
| Tool | Description |
| - | - |
| `entitlements_get` | Fetch entitlements for a customer. Pass `featureId` to scope. |
| `license_activate` | Activate a license key for a specific instance. Returns `instanceId`. |
| `license_deactivate` | Deactivate a license instance. |
| `license_validate` | Validate a license key (optionally bound to an instance). |
| `usage_report` | Report metered usage. `behaviour: SET` replaces, `DELTA` increments. |
### Offerings & Promotions
| Tool | Description |
| - | - |
| `offering_get_product` | Fetch public pricing scoped to a product UUID. Includes localized prices + customer subscription state. |
| `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key. |
### Discounts
| Tool | Description |
| - | - |
| `discount_list` | List discount codes. Optional `search` across name and code, paginated. |
| `discount_create` | Create a percentage or fixed-amount code, optionally limited to a product (identifier or UUID) and its plans with `appliesTo`. Merchant of Record organizations only. |
| `discount_retrieve` | Fetch one discount, including how often it's been redeemed and whether it's active. |
| `discount_update` | Enable or disable a code with `isActive`. Nothing else can change after creation. |
| `discount_archive` | Archive a code so it can no longer be used. |
### Webhooks
| Tool | Description |
| - | - |
| `webhook_endpoint_list` | List endpoints with their URLs, events and enabled state. |
| `webhook_endpoint_create` | Register a public URL for the events you choose. Localhost and private addresses are rejected. |
| `webhook_endpoint_retrieve` | Fetch one endpoint. |
| `webhook_endpoint_update` | Change an endpoint's URL, events or enabled state. |
| `webhook_endpoint_delete` | Delete an endpoint. Deliveries stop immediately. |
| `webhook_log_list` | Delivery attempts from the last 30 days, with status codes and retries. |
Signing secrets are hidden in webhook tool results. Pass `revealSecret: true` only when you need the value — your app reads the secret from its env file, so it rarely needs to appear in a conversation.
### Catalog: Products
| Tool | Description |
| - | - |
| `product_list` | List catalog products. Optional `search` substring + `page`. |
| `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` (S3 file keys from the `POST /media/` API endpoint). |
| `product_retrieve` | Fetch one product by UUID or identifier. |
| `product_update` | Patch a product. |
| `product_archive` | Archive (soft-delete) a product. |
| `product_settings_get` | VPN / Tor / proxy policy, default currency, product URL. |
| `product_settings_update` | Patch any subset of those settings. |
| `product_image_update` | Edit display fields of a product image (`name`, `ordering`, `thumbnail`, `enabled`). |
| `product_image_delete` | Remove an image from a product. |
### Catalog: Features
| Tool | Description |
| - | - |
| `feature_list` | List catalog features. |
| `feature_create` | Create a feature. Required: `name`, `featureType` (`BOOLEAN` / `CUSTOMIZABLE` / `METER`). |
| `feature_retrieve` | Fetch one feature. |
| `feature_archive` | Archive a feature. Plans referencing it keep working. |
### Catalog: Plans
Plans are versioned. Updates create a draft; `plan_publish` releases it.
| Tool | Description |
| - | - |
| `plan_list` | List all plans in the account. |
| `plan_create` | Create a plan under a product (by identifier or UUID). Plan starts in `DRAFT`. |
| `plan_retrieve` | Fetch one plan. |
| `plan_update` | Patch a plan. Updates to a published plan automatically create a new draft. |
| `plan_archive` | Archive a plan. Existing subscriptions keep working. |
| `plan_publish` | Publish the latest draft. `updateFeatures` / `updatePricing` flags migrate existing customers. |
| `plan_discard_draft` | Drop the current draft, keep the published version. |
| `plan_prices_list` | List all prices configured on a plan. |
| `plan_entitlements_list` | List feature entitlements on a plan. |
| `plan_entitlements_add` | Attach feature entitlements, each feature by identifier or UUID. |
| `plan_entitlement_update` | Patch a single entitlement's `details`. |
| `plan_entitlement_delete` | Remove an entitlement. |
| `plan_file_update` | Edit display fields of a plan-attached file. |
| `plan_file_delete` | Remove a file from a plan. |
| `plan_file_download` | Download URL/stream for a plan file (buyer-facing deliverables). |
### Docs (no API key required)
| Tool | Description |
| - | - |
| `docs_search` | Full-text search across the bundled Kelviq docs. Returns `{slug, title, snippet, score}`. |
| `docs_read` | Fetch a full markdown doc by slug. |
***
## Resources
Resources let your AI client pin pages into context. The server advertises three categories:
| URI pattern | Content |
| - | - |
| `kelviq://docs/{section}/{slug}` | Every page in the Kelviq docs |
| `kelviq://openapi.json` | The full OpenAPI 3.0 spec (every operation and schema) |
| `kelviq://README` | Top-level Kelviq overview |
For exhaustive per-endpoint request/response shapes, the **OpenAPI spec is the source of truth**. Ask your assistant *"check the OpenAPI spec for createSubscription"* and it will read the resource directly.
***
## Built-in Prompts
The server ships three MCP prompts that encode Kelviq's golden-path workflows — including the gotchas (plans start as invisible drafts until published; features attach by identifier or UUID; pricing is set in the dashboard or with the [Kelviq CLI](/cli/overview), not through the MCP server). In Claude Code they appear as slash commands (e.g. `/kelviq:setup_product`); other MCP clients list them under prompts.
| Prompt | Arguments | What it guides |
| - | - | - |
| `setup_product` | `productName?`, `planName?` | Full catalog bootstrap: product → features → plan → entitlements → publish → verify. |
| `launch_plan` | `productId?`, `planName?` | Add and publish a new plan on an existing product, reusing existing features. |
| `diagnose_customer` | `customerId` | Cross-check a customer's entitlements, subscriptions, and plan configuration; ends with concrete next actions. |
## Example Prompts
Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
> **Build a catalog from scratch**
>
> > *Create a Kelviq product called "Notion Plus" with tax code `saas`, then create three plans (Free, Pro Monthly, Pro Yearly), add an `api-calls` feature with limits 1000 / 50000 / unlimited, and publish all three plans.*
>
> Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `plan_publish` × 3. Set each plan's prices in the [dashboard](https://app.kelviq.com) or with the [Kelviq CLI](/cli/overview), which manages pricing as reviewable code.
> **Issue a checkout link**
>
> > *Create a checkout session for plan `pro-monthly` for a new customer, success URL [https://example.com/done](https://example.com/done).*
>
> Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
> **License key management**
>
> > *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
>
> Calls: `license_activate` → `license_validate`.
> **Inspect customer state**
>
> > *Show me all subscriptions for customer `acme-42` and tell me which features they have access to.*
>
> Calls: `subscription_list` → `entitlements_get`.
> **Documentation lookup**
>
> > *How do digital downloads work in Kelviq? What's the file-size limit?*
>
> Calls: `docs_search` → `docs_read`. No API key needed — works offline.
***
## Tips for Effective Prompts
* **Mention "Kelviq" early.** LLMs typically have many MCP tools loaded. Saying "create a *Kelviq* customer" steers the model toward this server's tools instead of guessing.
* **Use `docs_search` for fuzzy questions.** When you're unsure of an identifier or behaviour, ask the LLM to *"search Kelviq docs"* first — it grounds the follow-up calls in real semantics.
* **Trust the errors.** Tools return `{"error": {"status", "message"}}` shapes for API errors. The LLM reads them and adjusts automatically (e.g. "Invalid product identifier" → asks you for the right one).
* **Combine tools in one prompt.** The LLM is happy to chain calls. "Create the product, then publish all its plans" is one prompt, not five.
***
## Troubleshooting
### `Executable not found in $PATH: "node"` in Claude Code
GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to them. Pick one fix:
1. **Symlink node into a system path** (recommended):
```bash theme={null}
sudo ln -s "$(which node)" /usr/local/bin/node
```
One-time fix for every MCP server you'll ever add.
2. **Use the absolute node path:**
```bash theme={null}
claude mcp add kelviq \
--env KELVIQ_SERVER_API_KEY=... \
-- /Users/you/.nvm/versions/node/v20.19.0/bin/node \
$(npm root -g)/@kelviq/mcp-server/dist/server.js
```
3. **Install Node via Homebrew:**
```bash theme={null}
brew install node
```
Puts `node` on the system PATH so all GUI tools see it.
### `error: unknown option '-y'` from `claude mcp add`
`claude` is intercepting `-y` as one of its own flags. Use `--` to separate Claude's args from the actual command:
```bash theme={null}
claude mcp add kelviq \
--env KELVIQ_SERVER_API_KEY=... \
-- npx -y @kelviq/mcp-server@latest
```
### Tool returns `{"error": {"status": "Configuration error", ...}}`
A required env var is missing. The error message names which one — set it in your client config and reconnect.
### Tool returns HTTP 401 or 403
Ask your assistant to call `connection_check`: it reports the environment the server is using and whether the key was accepted, without showing the key. Almost always, the key belongs to the other environment: a sandbox key only works against sandbox, and a production key only against production.
* The server uses sandbox unless `KELVIQ_ENV=production`. If your key is a production key, add `KELVIQ_ENV=production` to the server's environment and reconnect.
* The error message includes a hint naming the environment the server is using, and the startup log shows it too (`kelviq-mcp ready (env=…`). Make sure it matches your key.
* If neither shows an environment, your client is running an outdated copy of the server. Use `npx -y @kelviq/mcp-server@latest` in your client config.
### Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
Your API key works but the identifier doesn't exist on this account. Most common cause: the identifier exists in the other environment — sandbox and production have separate catalogs. Check `KELVIQ_ENV`.
### Test Without an AI Client
Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to browse and call tools directly from a browser:
```bash theme={null}
KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
npx -y @modelcontextprotocol/inspector \
npx -y @kelviq/mcp-server@latest
```
***
## Source & Contributing
* **npm** — [`@kelviq/mcp-server`](https://www.npmjs.com/package/@kelviq/mcp-server)
* **GitHub** — [`kelviq/kelviq-mcp-server`](https://github.com/kelviq/kelviq-mcp-server)
* **Issues** — [github.com/kelviq/kelviq-mcp-server/issues](https://github.com/kelviq/kelviq-mcp-server/issues)
* **License** — MIT
The repo is the canonical reference for tool schemas, build process, and contribution guidelines. New Kelviq API endpoints are added by extending the hand-written Zod schemas in `src/schemas/kelviq.ts` and the per-domain files in `src/tools/`.
***
## Need Help?
* Email us at **[hi@kelviq.com](mailto:hi@kelviq.com)**
* [Book a demo](https://cal.com/alok-vats-fkpnc9/30min)
# Migrate from Cashfree
Source: https://docs.kelviq.com/guides/migrate-from-cashfree
Get help moving from Cashfree to Kelviq
Need help moving from Cashfree to Kelviq? Contact [hi@kelviq.com](mailto:hi@kelviq.com) to discuss your current setup.
# Sandbox
Source: https://docs.kelviq.com/guides/sandbox
Build and test your Kelviq integration without affecting production data or processing real payments
Kelviq's sandbox is a separate environment for development and testing. You can configure products and plans, create customers, exercise checkout flows, and test your integration without affecting your live organization or processing real payments.
## How isolation works
Sandbox and production use separate data and credentials.
| Resource | Sandbox behavior |
| - | - |
| Data | Products, plans, customers, subscriptions, and orders are isolated from production |
| API keys | Work only with sandbox hosts |
| Payments | Use test card details; no real charge is made |
This separation prevents development activity from changing live customer or billing data. Before launch, configure the resources your integration needs in production and replace all sandbox credentials and URLs.
## Get started
1. Sign in to the [Kelviq dashboard](https://app.kelviq.com).
2. Open the organization dropdown and click **Enter sandbox**.
3. Create the products, plans, prices, and other test data you need.
4. Open **Settings → API keys** and copy the sandbox key required by your integration.
> [!WARNING]
>
> Never use a production Server API Key in test code. Store Server API Keys in environment variables and use Client API Keys only in supported browser integrations.
## Connect to the sandbox API
Use the sandbox hosts with sandbox-scoped credentials:
| API | Sandbox base URL |
| - | - |
| Core API | `https://sandboxapi.kelviq.com/api/v1` |
| Edge API | `https://edge.sandboxapi.kelviq.com/api/v1` |
For example:
```bash theme={null}
curl https://sandboxapi.kelviq.com/api/v1/catalog/products/ \
--header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
--header "Accept: application/json"
```
Changing only the URL is not enough: the request must also use an API key created while the dashboard is in Sandbox mode.
## Use the sandbox with an SDK
Set `environment` to `sandbox` when initializing an official SDK.
```typescript Node.js theme={null}
import { Kelviq } from "@kelviq/node-sdk";
const client = new Kelviq({
accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
environment: "sandbox",
});
```
```python Python theme={null}
from kelviq_sdk import Kelviq
client = Kelviq.create_sync_client(
access_token=KELVIQ_SANDBOX_SERVER_API_KEY,
environment="sandbox",
)
```
```tsx React theme={null}
{children}
```
See the [Node SDK](/backend-integration/node-sdk), [Python SDK](/backend-integration/python-sdk), or [frontend SDK guides](/frontend-integration/react-sdk) for full setup instructions.
## Test checkout
Create a checkout in the sandbox and use these test card details. Use any future expiration date and a valid test CVC.
| Card number | Result |
| - | - |
| `4242 4242 4242 4242` | Successful payment |
| `4000 0000 0000 0002` | Declined payment |
| `4000 0025 0000 3155` | Payment requiring authentication |
> [!WARNING]
>
> Do not enter a real card number in the sandbox.
After payment, confirm that the test order, customer, subscription, and entitlements have the expected state in Sandbox mode.
## Test a subscription renewal
> [!NOTE]
>
> Daily billing is not enabled by default. Any sandbox organization can request it by contacting [Kelviq support](mailto:hi@kelviq.com).
After Daily billing is enabled, use it to test a renewal without waiting for a monthly or yearly billing cycle.
1. Enter Sandbox mode in the Kelviq dashboard.
2. Open the test plan you want to use.
3. Under **Billing cycles**, select **Daily** and enter a test price.
4. Publish the plan.
5. Start a subscription with a sandbox test card.
6. After the next billing cycle, check the order, invoice, subscription status, and entitlements in Sandbox mode.
If you create the checkout session through the API, set `chargePeriod` to `DAILY`:
```json theme={null}
{
"planIdentifier": "sandbox-renewal-test",
"chargePeriod": "DAILY",
"customerId": "test-customer-001",
"successUrl": "https://example.com/billing/success"
}
```
## Can I test production with my own card?
No. Do not place a live order using your own card just to test production credentials. Payment providers can treat a self-payment as suspicious and block the card, even when the amount is small. There is no safe minimum price for this test.
Use one of these options instead:
* Keep payment and renewal testing in Sandbox.
* If you need to inspect the production checkout, [create a 100% discount code](/product-catalog/discounts) so no real payment is collected.
* Check production credentials, URLs, and environment settings without completing a purchase.
## Prepare for production
Before accepting live payments:
1. Complete the required [business review and payout setup](/getstarted/review-process).
2. Configure and publish your production products and plans.
3. Replace sandbox API keys with production API keys.
4. Replace sandbox base URLs or set each SDK's environment to `production`.
5. Run a final check that no sandbox credentials or hosts remain in your production configuration.
> [!TIP]
>
> Use clearly named variables such as `KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` to reduce the chance of mixing environments.
# Set up with AI
Source: https://docs.kelviq.com/guides/set-up-with-ai
Hand billing to your AI coding agent with a prompt generated from your Kelviq account
**Settings → Set up with AI** writes a prompt for your coding agent. Paste it into Claude Code, Cursor, Codex, Lovable, Replit, Bolt, or any agent that can edit files and run commands, and the agent integrates Kelviq into your app.
It asks before changing anything in Kelviq and never needs your keys in the chat. Your agent can build and test everything with sandbox keys, then you go live when it's ready. You can also set it up directly in production.
## Two ways to start
**Integrate with my app** is for a catalog you have already built. The agent connects the plans you have published: it adds a checkout route, a billing portal route, feature checks, and a webhook route that verifies signatures. If your app has a public URL, it registers the webhook too.
**Set up everything** is for a new product. The agent reads your app and your requirements, proposes plans, prices, limits, license keys and discount codes, and shows you what it will create. Nothing is created in Kelviq until you approve. It then builds the integration the same way.
## Steps
1. **Add your keys to the project.** Click **Copy for your .env file** and paste the block into your project's `.env.local` or `.env`, or into your app builder's secrets. The agent reads the keys from the file. Don't paste them into the chat.
2. **Describe what you want.** Plain language is fine: "one plan at \$9/month with license keys, up to 3 devices per key, no free plan". Or add a common request, such as a monthly and yearly toggle or a 7-day free trial. The agent follows these on top of its defaults and asks if something conflicts.
3. **Give the prompt to your agent.** Click **Copy prompt**, open your agent in your app's project, and paste it as the first message.
The agent checks your keys with the Kelviq CLI without printing them and builds the app. In sandbox, it ends with a test purchase you can try with a [test card](/guides/sandbox).
## Sandbox or production
The page gives you keys and a prompt for the mode you're in. Switch to sandbox in the dashboard to get sandbox keys and a sandbox prompt.
[Business verification](/getstarted/review-process) and adding your keys to your project stay with you.
On Claude Code, install the [Kelviq plugin](/guides/agent-toolkit) for extra tools. The prompt picks them up automatically.
## Related documentation
* [Agent Toolkit](/guides/agent-toolkit)
* [MCP server](/guides/mcp-server)
* [CLI overview](/cli/overview)
# Subscription Integration
Source: https://docs.kelviq.com/guides/subscription-integration
A simple guide to add subscription billing to your SaaS in 5 API calls.
Add subscription billing to your SaaS with just a few API calls. This guide covers the REST API — for framework-specific guides, see [Next.js Integration](/guides/subscription-integration-for-nextjs).
***
## Overview
Kelviq handles your subscription billing with these endpoints:
| Step | Endpoint | Purpose |
| - | - | - |
| 1 | Create Customer | Register user (optional) |
| 2 | Create Checkout | Start payment flow |
| 3 | Get Subscription | Check active plans |
| 4 | Update Subscription | Upgrade/downgrade |
| 5 | Check Entitlements | Gate features |
***
## Step 1: Create Customer (Optional)
You have two options for creating customers:
### Option 1: Auto-create during checkout
Skip this step. Pass `email` or `customerId` in the checkout request — Kelviq will auto-create the customer.
### Option 2: Create customer explicitly
Create a customer record when a user signs up.
```javascript theme={null}
const response = await fetch("https://api.kelviq.com/api/v1/customers/", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SERVER_API_KEY"
},
body: JSON.stringify({
customerId: "user-123",
name: "John Doe",
email: "john@example.com"
})
});
const customer = await response.json();
```
> [!TIP]
>
> Pre-creating customers is useful when you want to track users in the dashboard before they subscribe.
***
## Step 2: Create Checkout Session
When a user wants to subscribe, create a checkout session and redirect them.
### Request
```javascript theme={null}
const response = await fetch("https://api.kelviq.com/api/v1/checkout/", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SERVER_API_KEY"
},
body: JSON.stringify({
planIdentifier: "pro",
chargePeriod: "MONTHLY",
customerId: "user-123",
successUrl: "https://yourapp.com/success"
})
});
const { checkoutUrl } = await response.json();
```
### Response
```json theme={null}
{
"checkoutUrl": "https://www.kelviq.com/checkout/cs_fBhCIBerpe1pAsRW6P4wYc8WHqMdfdr457hd3oOLjhAFx/",
"checkoutSessionId": "cs_test_b1sNi7D6u9iMCUFV1UZi9ZwerfaiXKdOOmr3DCUW6XdCZIr5Id1F7G"
}
```
> [!NOTE]
>
> Redirect user to `checkoutUrl` → They complete payment → Redirected back to your `successUrl`
### Required Parameters
| Parameter | Description |
| - | - |
| `planIdentifier` | The identifier of the plan (e.g., `"pro"`, `"enterprise"`) |
| `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"TWENTY_EIGHT_DAYS"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
| `successUrl` | URL to redirect after successful payment |
### Optional Parameters
| Parameter | Description |
| - | - |
| `customerId` | Your customer ID (auto-creates if new) |
| `offeringId` | UUID of the offering |
| `pricingTableId` | UUID of the pricing table |
| `ipAddress` | Customer IP for location-based pricing |
***
## Step 3: Get Subscription Details
Check if a customer has an active subscription.
### Request
```javascript theme={null}
const response = await fetch(
"https://api.kelviq.com/api/v1/subscriptions/?customer_id=user-123",
{
headers: {
"Authorization": "Bearer YOUR_SERVER_API_KEY"
}
}
);
const { results } = await response.json();
const activeSubscription = results.find(s => s.status === "active");
```
### Response
```json theme={null}
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
"status": "active",
"plan": {
"name": "Pro Plan",
"identifier": "pro"
},
"amount": "49.00",
"recurrence": "month",
"currency": "usd",
"startDate": "2024-01-01",
"endDate": null,
"customerId": "user-123"
}
]
}
```
> [!NOTE]
>
> Kelviq handles failed card payment retries and emails the customer a link to pay. Your application does not need its own retry process or payment recovery screen. See [Failed subscription payments](/product-catalog/subscriptions#failed-subscription-payments).
***
## Step 4: Update Subscription
Allow users to upgrade or downgrade their plan.
### Request
```javascript theme={null}
const response = await fetch(
"https://api.kelviq.com/api/v1/subscriptions/09d706ca-58f3-4fb2-818f-5b8623d67e6e/update/",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SERVER_API_KEY"
},
body: JSON.stringify({
planIdentifier: "enterprise",
chargePeriod: "MONTHLY",
paymentBehavior: "activate_on_payment"
})
}
);
const data = await response.json();
```
### Response
```json theme={null}
{
"subscriptionId": "09d706ca-58f3-4fb2-818f-5b8623d67e6e"
}
```
### Required Parameters
| Parameter | Description |
| - | - |
| `planIdentifier` | The identifier of the new plan |
| `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, etc. |
### Optional Parameters
| Parameter | Description |
| - | - |
| `paymentBehavior` | Set to `"activate_on_payment"` to keep the current subscription active until payment for the change succeeds. Omit it to apply the update immediately. |
### Activation after payment
Use `activate_on_payment` when a plan change should not affect access until Kelviq has collected payment.
| Payment path | What happens |
| - | - |
| Saved card with no customer action | Kelviq processes the payment immediately. The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
| UPI, 3DS, or another method requiring customer action | The updated subscription starts as `incomplete`. The existing subscription stays `active` until payment succeeds. |
| Payment succeeds | The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
| The immediate charge fails, or payment is not completed before expiry | The updated subscription becomes `incomplete_expired`. The existing subscription remains `active`. |
> [!WARNING]
>
> Do not grant the new plan's entitlements just because the update request returned successfully. Confirm that the updated subscription is `active`, or read the customer's current entitlements.
***
## Step 5: Check Entitlements
Check what features a customer has access to based on their subscription.
### Request
```javascript theme={null}
const response = await fetch(
"https://edge.api.kelviq.com/api/v1/entitlements/?customerId=user-123",
{
headers: {
"Authorization": "Bearer YOUR_CLIENT_API_KEY"
}
}
);
const { entitlements } = await response.json();
```
> [!WARNING]
>
> Use your **Client API Key** for this endpoint, not your Server API Key.
### Response
```json theme={null}
{
"customerId": "user-123",
"entitlements": [
{
"featureId": "export-data",
"featureType": "BOOLEAN",
"hasAccess": true
},
{
"featureId": "max-projects",
"featureType": "METER",
"hasAccess": true,
"usageLimit": 100,
"currentUsage": 45,
"remaining": 55
},
{
"featureId": "team-size",
"featureType": "CUSTOMIZABLE",
"hasAccess": true,
"usageLimit": 5
}
]
}
```
### Entitlement Types
| Type | Description | Fields |
| - | - | - |
| **BOOLEAN** | Feature on/off | `hasAccess` |
| **METER** | Usage-based limits | `usageLimit`, `currentUsage`, `remaining` |
| **CUSTOMIZABLE** | Configurable value | `usageLimit` |
***
## Complete Flow
```
1. User signs up
→ Create customer via API (or auto-create via email)
2. User visits pricing page
→ Create checkout session
→ Redirect to checkout URL
→ User completes payment
→ Redirect back to your app
3. In your app
→ Get subscription details
→ Check entitlements
→ Show/hide features based on access
4. User wants to upgrade
→ Update the subscription with paymentBehavior: "activate_on_payment"
→ Keep the existing subscription active while payment is pending
→ After payment succeeds, the new subscription becomes active
→ The previous subscription becomes superseded
```
***
## Need Help?
Have questions or need implementation support?
* Email us at **[hi@kelviq.com](mailto:hi@kelviq.com)**
* [Book a demo](https://cal.com/alok-vats-fkpnc9/30min)
# Subscription Integration for Next.js
Source: https://docs.kelviq.com/guides/subscription-integration-for-nextjs
A step-by-step guide to add subscription billing and entitlements to your Next.js app.
Integrate Kelviq subscription billing into your Next.js application using the App Router and React SDK.
***
## Prerequisites
* Next.js 14+ with App Router
* A Kelviq account with plans configured
* API keys from **Settings → API keys** in the dashboard
***
## Step 1: Get Your API Keys
1. Sign up at [app.kelviq.com](https://app.kelviq.com)
2. Navigate to **Settings → API keys**
3. Copy two keys:
* **Server API Key** — For API routes (keep secret)
* **Client API Key** — For React SDK (safe to expose)
### Add to Environment Variables
Add these to your `.env.local` file:
```env theme={null}
# Backend (server-side only)
KELVIQ_SERVER_API_KEY=server-xxxxxxxx
KELVIQ_ENV=sandbox
# Frontend (can be exposed to client)
NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY=client-xxxxxxxx
NEXT_PUBLIC_KELVIQ_ENV=sandbox
# Your app URL (for redirects)
NEXT_PUBLIC_APP_URL=https://yourdomain.com
```
Build with sandbox keys — keys only work against their own environment. When you go live, switch both keys to production keys and set both `KELVIQ_ENV` values to `production`.
> [!WARNING]
>
> Never expose your server API key to the frontend or commit it to version control.
### Point API Routes at the Right Environment
Create `lib/kelviq.ts` so every API route calls the host that matches `KELVIQ_ENV`:
```typescript theme={null}
export const KELVIQ_API_URL =
process.env.KELVIQ_ENV === "production"
? "https://api.kelviq.com/api/v1"
: "https://sandboxapi.kelviq.com/api/v1";
```
***
## Step 2: Define Your Plans
### In Kelviq Dashboard
1. Go to **Product catalog → Products**, open your product, and add a plan for each tier with:
* **Plan Identifier**: `base`, `pro`, `enterprise` (code-friendly names)
* **Price**: Monthly/yearly pricing
* **Features**: List of included features
### Add features & limits
For each plan, add features & limits:
| Type | Description | Example |
| - | - | - |
| **Boolean (`BOOLEAN`)** | Feature is on/off | `export-data` |
| **Meter feature (`METER`)** | Feature has usage limits | `max-projects: 10` |
| **Customizable (`CUSTOMIZABLE`)** | Feature has configurable value | `team-size: 5` |
**Example Plan Structure:**
| Feature | Base (\$9/mo) | Pro (\$49/mo) | Enterprise (\$199/mo) |
| - | - | - | - |
| max-projects | 10 | 100 | Unlimited |
| export-data | No | Yes | Yes |
| team-size | 1 | 5 | 50 |
***
## Step 3: Install the React SDK
```bash theme={null}
npm install @kelviq/react-sdk
```
***
## Step 4: Create Customers (Optional)
You have two options for creating customers in Kelviq:
### Option 1: Auto-create during checkout
Skip this step entirely. When creating a checkout session, pass the customer's `email` or `customerId` — Kelviq will automatically create the customer record if it doesn't exist.
### Option 2: Create customer explicitly
Create a customer record when a user signs up. This gives you more control and lets you track customers before they subscribe.
**Create API Route** — `app/api/customer/route.ts`:
```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";
import { KELVIQ_API_URL } from "@/lib/kelviq";
export async function POST(request: NextRequest) {
const { customerId, name, email } = await request.json();
const response = await fetch(
`${KELVIQ_API_URL}/customers/`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
},
body: JSON.stringify({ customerId, name, email }),
}
);
const data = await response.json();
return NextResponse.json(data, { status: response.status });
}
```
**Call from Client Component:**
```typescript theme={null}
async function createKelviqCustomer(userId: string) {
await fetch("/api/customer", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
customerId: userId, // Your internal user ID
name: "John Doe",
email: "john@example.com",
}),
});
}
```
> [!TIP]
>
> Pre-creating customers is useful when you want to track users in the Kelviq dashboard before they subscribe, or when you need to store additional customer metadata.
***
## Step 5: Implement Checkout
Allow users to subscribe to a plan.
### Create Checkout API Route
Create `app/api/checkout/route.ts`:
```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";
import { KELVIQ_API_URL } from "@/lib/kelviq";
export async function POST(request: NextRequest) {
const { planIdentifier, customerId, chargePeriod } = await request.json();
const response = await fetch(
`${KELVIQ_API_URL}/checkout/`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
},
body: JSON.stringify({
planIdentifier,
chargePeriod: chargePeriod || "MONTHLY",
customerId, // Customer auto-created if new
successUrl: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
}),
}
);
const data = await response.json();
return NextResponse.json(data);
}
```
### Pricing Page
Create `app/pricing/page.tsx`:
```tsx theme={null}
"use client";
const plans = [
{ id: "base", name: "Base", price: 9 },
{ id: "pro", name: "Pro", price: 49 },
{ id: "enterprise", name: "Enterprise", price: 199 },
];
export default function PricingPage() {
const handleSubscribe = async (planId: string) => {
const response = await fetch("/api/checkout", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
planIdentifier: planId,
customerId: getCurrentUserId(), // Your auth system
}),
});
const { checkoutUrl } = await response.json();
window.location.href = checkoutUrl;
};
return (
{plans.map(plan => (
{plan.name}
${plan.price}/month
))}
);
}
```
**Success Page Example**
Create `app/success/page.tsx`:
```tsx theme={null}
export default function SuccessPage() {
return (
);
}
```
***
## Step 6: Manage Subscriptions
### Fetch Current Subscription
Create `app/api/subscriptions/route.ts`:
```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";
import { KELVIQ_API_URL } from "@/lib/kelviq";
export async function GET(request: NextRequest) {
const customerId = request.nextUrl.searchParams.get("customerId");
const response = await fetch(
`${KELVIQ_API_URL}/subscriptions/?customer_id=${customerId}`,
{
headers: {
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
},
}
);
const data = await response.json();
return NextResponse.json(data);
}
```
### Update Subscription (Upgrade/Downgrade)
Create `app/api/subscriptions/update/route.ts`:
```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";
import { KELVIQ_API_URL } from "@/lib/kelviq";
export async function POST(request: NextRequest) {
const {
subscriptionId,
planIdentifier,
chargePeriod,
paymentBehavior,
} = await request.json();
const response = await fetch(
`${KELVIQ_API_URL}/subscriptions/${subscriptionId}/update/`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
},
body: JSON.stringify({
planIdentifier,
chargePeriod: chargePeriod || "MONTHLY",
paymentBehavior,
}),
}
);
const data = await response.json();
return NextResponse.json(data);
}
```
### Handle Upgrades/Downgrades in Client
```typescript theme={null}
async function handlePlanChange(newPlanId: string) {
// Fetch current subscription
const res = await fetch(`/api/subscriptions?customerId=${userId}`);
const { results } = await res.json();
const current = results.find(s => s.status === "active");
if (current) {
// Update existing subscription
await fetch("/api/subscriptions/update", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
subscriptionId: current.id,
planIdentifier: newPlanId,
chargePeriod: "MONTHLY",
paymentBehavior: "activate_on_payment",
}),
});
alert("Plan change started. The new plan becomes active after payment succeeds.");
} else {
// No subscription, redirect to checkout
}
}
```
With `activate_on_payment`, the existing subscription remains `active` while payment is pending. If the payment method requires UPI approval or 3DS authentication, the updated subscription starts as `incomplete`. After payment succeeds, the updated subscription becomes `active` and the previous subscription becomes `superseded`. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes `incomplete_expired` and the existing subscription stays active.
> [!WARNING]
>
> Do not unlock the new plan immediately after this route returns. Check the updated subscription status or fetch the customer's current entitlements first.
***
## Step 7: Gate Features with Entitlements
Dynamically enable/disable features based on subscription.
### Setup KelviqProvider
Wrap your app in `app/layout.tsx`:
```tsx theme={null}
import { KelviqProvider } from "@kelviq/react-sdk";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
### Access Entitlements in Components
```tsx theme={null}
"use client";
import { useKelviq, useAllEntitlements } from "@kelviq/react-sdk";
export function MyFeature() {
const { isLoading, error } = useKelviq();
const entitlementsState = useAllEntitlements();
const entitlements = entitlementsState?.data;
if (isLoading) return Loading...;
if (error) return Error loading features;
// Boolean entitlement example
const canExport = entitlements?.["export-data"]?.hasAccess ?? false;
// Metered entitlement example
const maxProjects = entitlements?.["max-projects"]?.usageLimit;
const currentProjects = entitlements?.["max-projects"]?.currentUsage ?? 0;
const remainingProjects = entitlements?.["max-projects"]?.remaining;
// Config entitlement example
const teamSize = entitlements?.["team-size"]?.usageLimit ?? 1;
return (
{/* Boolean: Show/hide feature */}
{canExport ? (
) : (
Export locked. Upgrade to unlock
)}
{/* Metered: Check usage limits */}
Projects: {currentProjects} / {maxProjects ?? "Unlimited"}
{/* Config: Use value */}
Team size: {teamSize} members
);
}
```
### Entitlement Response Structure (React SDK)
```typescript theme={null}
interface Entitlement {
featureId: string;
featureType: "BOOLEAN" | "METER" | "CUSTOMIZABLE";
hasAccess: boolean;
usageLimit: number | null; // For METER (summed) and CUSTOMIZABLE (first item)
currentUsage: number; // For METER (summed) and CUSTOMIZABLE (first item)
remaining: number | null; // For METER: usageLimit - currentUsage (null = unlimited)
hardLimit: boolean; // true if any item has a hard limit
items: RawEntitlement[]; // Raw API entries for this featureId
}
```
***
## Common Patterns
> **Pattern 1: Feature Lock UI**
>
> ```tsx theme={null}
> "use client";
>
> import { useAllEntitlements } from "@kelviq/react-sdk";
>
> function LockedFeature({ featureId }: { featureId: string }) {
> const entitlements = useAllEntitlements()?.data;
> const hasAccess = entitlements?.[featureId]?.hasAccess ?? false;
>
> if (!hasAccess) {
> return (
>
> Feature locked
> Upgrade to unlock
>
> );
> }
>
> return null;
> }
>
> // Usage
> {current} / {max ?? "Unlimited"} used
> {max && (
>
>
>
> )}
>
> );
> }
> ```
> **Pattern 3: Conditional Rendering**
>
> ```tsx theme={null}
> "use client";
>
> import { useAllEntitlements } from "@kelviq/react-sdk";
>
> function DashboardFeatures() {
> const entitlements = useAllEntitlements()?.data;
>
> const canExport = entitlements?.["export-data"]?.hasAccess;
> const canInviteTeam = entitlements?.["team-features"]?.hasAccess;
> const maxProjects = entitlements?.["max-projects"]?.usageLimit;
>
> return (
>
> Dashboard
>
> {canExport && `. Store this secret securely — you will need it to verify signatures.
> [!WARNING]
>
> Your signing secret is shown only once. If you lose it, you must regenerate it from the dashboard.
***
## Inspect and resend deliveries
Open **Settings → Webhooks** and select an endpoint to view its delivery logs. Each delivery shows the event type, status, response code, and response body.
To retry a delivery:
1. Fix the endpoint or deployment issue that caused the delivery to fail.
2. Open the failed delivery in the webhook logs.
3. Click **Resend**.
4. Review the new delivery attempt and its response.
Kelviq automatically retries timeouts, connection failures, and `5xx` or `429` responses, but not other `4xx` or `3xx` responses. Use a manual resend to redeliver those after you fix the endpoint, or to retry immediately instead of waiting for the next automatic attempt.
> [!WARNING]
>
> Automatic retries and manual resends can deliver the same event more than once. Process webhooks idempotently using the event `id` or the `webhook-id` header.
***
## Event Types
| Event | Description |
| - | - |
| `checkout.completed` | A customer successfully completed a checkout session and payment was collected. |
| `customer.created` | A new customer record was created in your organization. |
| `customer.updated` | A customer's profile data (name, email, metadata) was updated. |
| `order.created` | A new order was placed. |
| `order.updated` | An existing order was updated. |
| `order.refunded` | A full or partial refund was issued against an order. |
| `subscription.created` | A new subscription was activated for a customer. |
| `subscription.updated` | A subscription's details were modified — including when a cancellation is scheduled for the end of the current period (status stays active; `end_date` is set). |
| `subscription.cancelled` | A subscription actually reached cancelled status. For a period-end cancellation, this fires later, when the period ends — not at the moment it was scheduled. |
| `subscription.plan_changed` | A subscription was moved to a different plan. |
| `subscription.paused` | A customer paused their subscription from the customer portal. The payload includes `paused_at` and `pause_resumes_at`. No other subscription events are sent while it stays paused. |
| `subscription.resumed` | A paused subscription started billing again, either at its scheduled date or by a resume call. Clear any cached entitlement checks for the customer on both events. |
| `subscription.trial_will_end` | A subscription's trial period is ending soon. |
| `feature.usage_alert` | A customer's feature usage crossed a configured threshold. |
| `invoice.created` | A new invoice was generated. |
| `invoice.paid` | An invoice was paid and funds were collected. |
| `invoice.payment_failed` | A subscription invoice payment failed or requires customer action. |
| `refund.created` | A refund was initiated. |
| `refund.updated` | A refund's status changed (e.g., from pending to completed). |
| `payment_method.created` | A new payment method was added for a customer. |
| `payment_method.updated` | A payment method's status or default state changed. |
| `payment_method.deleted` | A payment method was removed from a customer. |
***
## Checkout, subscription, and payment lifecycle
### Checkout and subscription creation
`checkout.completed` confirms that checkout finished successfully, but it does not include `subscription_id`. Kelviq creates the subscription after checkout and sends its ID in `subscription.created`.
Use your customer identifier or checkout `metadata` to correlate the two events. See [Add metadata to checkout](/checkout/checkout-metadata) for request and webhook examples. Do not treat the checkout redirect as proof that a subscription has been created.
### Custom field responses
When a checkout session collects [custom fields](/checkout/custom-fields), the customer's responses are included as `custom_fields_data` in `data.object` of `checkout.completed` and of the `order.created`, `order.updated`, and `order.refunded` events for the resulting order. The object is keyed by custom field identifier and is empty (`{}`) when the session collected no custom fields.
### Successful invoice payments
Kelviq sends `invoice.paid` whenever an invoice is paid, including invoices that are created directly with a `PAID` status. Use this event for payment-driven work such as recording revenue, starting an asynchronous provisioning job, or notifying an internal system.
For request-time access checks, query the customer's current entitlements instead of relying on a local webhook-derived subscription state.
### Failed invoice payments
Kelviq sends `invoice.payment_failed` when a subscription invoice payment fails or requires customer action. Use `data.object.subscription_id` and the embedded `customer` to identify the affected account. The invoice `status` is `PAYMENT_FAILED` for a failed attempt and can remain `OPEN` when the payment requires customer action.
This event can be followed by `invoice.paid` if the customer completes authentication or a later retry succeeds. Handle both events idempotently and treat the latest invoice and subscription state as authoritative.
### Subscription end dates
Subscription webhook objects include `end_date` inside `data.object`. Kelviq sets the field when a subscription has been cancelled or is scheduled to cancel on a future date. Otherwise, the value is `null`.
Use `end_date` for the subscription's scheduled or final end. `billing_period_end_time` describes the current billing period instead and should not be treated as the subscription's cancellation date.
### Failed renewal payments
Kelviq does not currently send a separate `payment.failed` event. For a failed card renewal:
1. The subscription moves to `past_due`.
2. Kelviq emails the customer a payment link.
3. Kelviq sends `subscription.updated` with the new subscription state.
4. Kelviq retries collection up to eight times over 14 days.
5. If all recovery attempts fail, Kelviq cancels the subscription and sends `subscription.cancelled`.
Do not remove access when you receive the first `subscription.updated` with `past_due` unless that is your own policy. Use the final subscription status or a live entitlement check to decide when access should end.
> [!NOTE]
>
> The retry window applies only to card payments. Kelviq does not retry a failed non-card renewal; the subscription is cancelled after the failure.
### Billing period field names
Subscription payloads use `billing_period_start_time` and `billing_period_end_time`. Match these names exactly when parsing dates. They describe the current billing period; use `end_date` for the subscription's scheduled or final end.
### Plan changes
By default, Kelviq applies a plan change immediately, charges any prorated difference, and sends `subscription.plan_changed`. After the generated invoice is paid, Kelviq sends the related order and invoice events.
If you update a subscription with `paymentBehavior: "activate_on_payment"`, the existing subscription remains `active` while payment is pending. A payment method that requires customer action leaves the updated subscription in `incomplete`. After payment succeeds, the updated subscription becomes `active` and the previous subscription becomes `superseded`. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes `incomplete_expired` and the existing subscription remains active.
Do not provision the new plan from the update API response alone. Read the latest subscription status or query the customer's current entitlements before changing access.
### Pauses and resumes
A pause sends `subscription.paused` with `status: "paused"`, `paused_at`, and `pause_resumes_at`, which is `null` for an open-ended pause. Treat it like a cancellation for access: entitlement checks already return `false` for a paused customer, so clear any cached result when the event arrives (`client.entitlements.invalidateCache` in Node, `client.entitlements.invalidate_cache` in Python).
The subscription is quiet until it resumes. Renewals that fall inside the pause are skipped without `subscription.updated` or invoice events. `subscription.resumed` arrives when billing starts again, at the scheduled date or after a resume call, with `status: "active"` and a new billing period. Usage counters are reset at that point.
Both events fire whichever surface made the change: the dashboard, the customer portal, or your API call.
### Partial and full refunds
`order.refunded` identifies whether the order is partially or fully refunded through its `status`:
* `PARTIAL_REFUND` for a partial refund
* `REFUNDED` for a full refund
The `order.refunded` payload does not include the refunded amount. Read `amount` or `amount_units` from `refund.created` and `refund.updated` when you need the exact value.
***
## Request Headers
Every webhook request from Kelviq includes the following headers:
| Header | Description |
| - | - |
| `webhook-id` | A unique UUID identifying this specific webhook event delivery. |
| `webhook-timestamp` | Unix timestamp (seconds) of when the event was dispatched. |
| `webhook-signature` | HMAC-SHA256 signature. Format: `v1,{signature}` |
| `Content-Type` | Always `application/json`. |
***
## Payload Structure
The request body is a JSON object with the following top-level fields:
```json theme={null}
{
"id": "3a7f1c2d-8e4b-4a9f-b123-0e5d6c7a8b9e",
"type": "subscription.created",
"created_at": "2024-06-01T12:00:00Z",
"data": {
"object": { ... },
"previous_attributes": { ... }
}
}
```
| Field | Type | Description |
| - | - | - |
| `id` | `string` (UUID) | The unique ID of this event. Matches the `webhook-id` header. |
| `type` | `string` | The event type (e.g., `subscription.created`). |
| `created_at` | `string` (ISO 8601) | UTC timestamp of when the event was created. |
| `data.object` | `object` | The primary resource affected by the event. |
| `data.previous_attributes` | `object` | *(Update events only)* The resource's changed attributes before the event. Omitted if not applicable. |
> **Example: checkout.completed payload**
>
> ```json theme={null}
> {
> "id": "1619afec-caab-40c7-827c-6af4f3acc9a3",
> "type": "checkout.completed",
> "created_at": "2026-04-01T17:28:39Z",
> "data": {
> "object": {
> "id": "cs_jBy6ViggULoyDMW9ikaw4ydur1NUa6dCORT6vqKPbPPW8",
> "object": "checkout_session",
> "status": "success",
> "checkout_type": "ONE_TIME",
> "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "amount": "10.00",
> "amount_units": 1000,
> "currency": "USD",
> "discount_code": "",
> "features": null,
> "plan": {
> "name": "Exc Tax Plan",
> "version": 1,
> "identifier": "exc-tax-plan"
> },
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> },
> "metadata": {
> "order_ref": "ABC-123",
> "source": "pricing_page"
> },
> "custom_fields_data": {
> "company-name": "Acme Inc",
> "purchase-order-number": "PO-4821"
> },
> "data": {
> "name": "Geo",
> "email": "geojacob@example.com",
> "referer": null,
> "cancel_url": null,
> "success_url": null,
> "tax_behavior": "EXCLUSIVE",
> "discounts_enabled": true
> },
> "created_on": "2026-04-01T17:27:59Z",
> "modified_on": "2026-04-01T17:28:39Z"
> }
> }
> }
> ```
> **Example: customer.created payload**
>
> ```json theme={null}
> {
> "id": "0662641a-b415-46eb-a78a-c136ce12fa60",
> "type": "customer.created",
> "created_at": "2026-04-01T07:05:56Z",
> "data": {
> "object": {
> "id": "7dd79eff-180f-4b07-a213-ebafd29e9725",
> "object": "customer",
> "customer_id": "geo-jacob",
> "name": "Geo Jacob",
> "email": "geo@example.com",
> "details": {},
> "metadata": {},
> "billing_address": {},
> "subscriptions": 0,
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "created_on": "2026-04-01T07:05:56Z",
> "modified_on": "2026-04-01T07:05:56Z"
> }
> }
> }
> ```
> **Example: customer.updated payload**
>
> ```json theme={null}
> {
> "id": "221a4d03-1cf4-47ae-9ed8-9f8f79ae989d",
> "type": "customer.updated",
> "created_at": "2026-04-01T07:32:42Z",
> "data": {
> "object": {
> "id": "7dd79eff-180f-4b07-a213-ebafd29e9725",
> "object": "customer",
> "customer_id": "geo-jacob",
> "name": "Geo Jacob v2",
> "email": "geo@example.com",
> "details": {},
> "metadata": {},
> "billing_address": {},
> "subscriptions": 0,
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "created_on": "2026-04-01T07:05:56Z",
> "modified_on": "2026-04-01T07:32:42Z"
> },
> "previous_attributes": {
> "name": "Geo Jacob"
> }
> }
> }
> ```
> **Example: order.created payload**
>
> ```json theme={null}
> {
> "id": "3f6a9c2e-1b4d-4e8f-9a7c-5d2e8b1f4a60",
> "type": "order.created",
> "created_at": "2026-04-01T17:36:41Z",
> "data": {
> "object": {
> "id": "ORD-20260401173639-H8IO7",
> "object": "order",
> "status": "COMPLETE",
> "billing_type": "ONE_TIME",
> "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {}
> },
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "is_renewal": false,
> "custom_fields_data": {
> "company-name": "Acme Inc",
> "purchase-order-number": "PO-4821"
> },
> "paid_at": "2026-04-01T17:36:41Z",
> "amount_total": "10.00",
> "amount_total_units": 1000,
> "currency": "USD",
> "subscription_id": "2c78e8f0-892e-406c-9896-18c69d3026c4",
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "plan": {
> "name": "Exc Tax Plan",
> "version": 1,
> "identifier": "exc-tax-plan"
> },
> "features": null,
> "created_on": "2026-04-01T17:36:41Z",
> "modified_on": "2026-04-01T17:36:41Z"
> }
> }
> }
> ```
> **Example: order.updated payload**
>
> ```json theme={null}
> {
> "id": "7c1e4b9a-2d5f-4a3c-8e6b-0f9d2a7c3e51",
> "type": "order.updated",
> "created_at": "2026-04-01T17:36:41Z",
> "data": {
> "object": {
> "id": "ORD-20260401173639-H8IO7",
> "object": "order",
> "status": "COMPLETE",
> "billing_type": "ONE_TIME",
> "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "is_renewal": false,
> "custom_fields_data": {
> "company-name": "Acme Inc",
> "purchase-order-number": "PO-4821"
> },
> "paid_at": "2026-04-01T17:36:41Z",
> "amount_total": "10.00",
> "amount_total_units": 1000,
> "currency": "USD",
> "subscription_id": "2c78e8f0-892e-406c-9896-18c69d3026c4",
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "plan": {
> "name": "Exc Tax Plan",
> "version": 1,
> "identifier": "exc-tax-plan"
> },
> "features": null,
> "created_on": "2026-04-01T17:36:41Z",
> "modified_on": "2026-04-01T17:36:41Z"
> },
> "previous_attributes": {
> "status": "PENDING"
> }
> }
> }
> ```
> **Example: order.refunded payload**
>
> ```json theme={null}
> {
> "id": "c1fb8514-fec6-44fa-9196-7dabe2f153ac",
> "type": "order.refunded",
> "created_at": "2026-04-02T03:48:32Z",
> "data": {
> "object": {
> "id": "ORD-20260401173639-H8IO7",
> "object": "order",
> "status": "REFUNDED",
> "billing_type": "ONE_TIME",
> "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "is_renewal": false,
> "custom_fields_data": {
> "company-name": "Acme Inc",
> "purchase-order-number": "PO-4821"
> },
> "paid_at": "2026-04-01T17:36:41Z",
> "amount_total": "10.00",
> "amount_total_units": 1000,
> "currency": "USD",
> "subscription_id": "2c78e8f0-892e-406c-9896-18c69d3026c4",
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "plan": {
> "name": "Exc Tax Plan",
> "version": 1,
> "identifier": "exc-tax-plan"
> },
> "features": null,
> "created_on": "2026-04-01T17:36:41Z",
> "modified_on": "2026-04-02T03:48:32Z"
> },
> "previous_attributes": {
> "status": "COMPLETE"
> }
> }
> }
> ```
> **Example: subscription.created payload**
>
> ```json theme={null}
> {
> "id": "3a7f1c2d-8e4b-4a9f-b123-0e5d6c7a8b9e",
> "type": "subscription.created",
> "created_at": "2026-03-11T05:25:34Z",
> "data": {
> "object": {
> "id": "a22f1b2a-b922-4a28-9b0e-75e826988b4b",
> "object": "subscription",
> "status": "active",
> "plan": {
> "name": "Pro",
> "version": 1,
> "identifier": "pro"
> },
> "product": {
> "id": "b4ea7e75-5dbe-4b3b-96e0-9a31dfe5a600",
> "name": "Acme Analytics"
> },
> "amount": "21.24",
> "amount_units": 2124,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-03-11",
> "end_date": null,
> "billing_period_start_time": "2026-03-11T05:25:33Z",
> "billing_period_end_time": "2026-04-10T06:28:58Z",
> "trial_start": "2026-03-11T05:25:33Z",
> "trial_end": "2026-03-25T05:25:33Z",
> "customer": {
> "id": "1bb69d0f-39f8-4db8-aace-e003d6e5f3ed",
> "name": "Geo Jacob",
> "email": "geo@example.com",
> "customer_id": "1",
> "billing_address": {
> "city": "Bangalore",
> "line1": null,
> "line2": null,
> "state": "Karnataka",
> "country": "IN",
> "postal_code": "560001"
> }
> },
> "features": null,
> "organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c",
> "created_on": "2026-03-11T05:25:34Z",
> "modified_on": "2026-03-11T05:25:34Z"
> }
> }
> }
> ```
> **Example: subscription.updated payload**
>
> ```json theme={null}
> {
> "id": "be4b0fa8-2e82-4664-b4f8-c3ab1622086c",
> "type": "subscription.updated",
> "created_at": "2026-04-02T05:21:33Z",
> "data": {
> "object": {
> "id": "ff258fd6-9a31-4eda-b3c8-000a24530890",
> "object": "subscription",
> "status": "active",
> "amount": "40.00",
> "amount_units": 4000,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-04-02",
> "end_date": null,
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "features": null,
> "plan": {
> "name": "Inc tax sub",
> "version": 1,
> "identifier": "inc-tax-sub"
> },
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "bc43b1a034a643309ee39d2f1a4d2131",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "billing_period_start_time": "2026-04-02T05:04:43Z",
> "billing_period_end_time": "2026-05-02T05:04:43Z",
> "trial_start": "2026-04-02T05:04:43Z",
> "trial_end": "2026-04-16T05:04:43Z",
> "created_on": "2026-04-02T05:21:28Z",
> "modified_on": "2026-04-02T05:21:33Z"
> },
> "previous_attributes": {
> "status": null,
> "billing_period_start_time": null
> }
> }
> }
> ```
> **Example: subscription.cancelled payload**
>
> ```json theme={null}
> {
> "id": "cacae554-d67e-4c6c-9d51-9d68f5c9b574",
> "type": "subscription.cancelled",
> "created_at": "2026-04-02T05:02:47Z",
> "data": {
> "object": {
> "id": "0faa77b7-2d42-4b6f-b682-d012987adad2",
> "object": "subscription",
> "status": "canceled",
> "amount": "40.00",
> "amount_units": 4000,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-04-02",
> "end_date": "2026-05-02",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "features": null,
> "plan": {
> "name": "Inc tax sub",
> "version": 1,
> "identifier": "inc-tax-sub"
> },
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "bc43b1a034a643309ee39d2f1a4d2131",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "billing_period_start_time": "2026-04-02T04:25:13Z",
> "billing_period_end_time": "2026-05-02T04:25:13Z",
> "trial_start": "2026-04-02T04:25:13Z",
> "trial_end": "2026-04-16T04:25:13Z",
> "created_on": "2026-04-02T04:25:20Z",
> "modified_on": "2026-04-02T05:02:47Z"
> },
> "previous_attributes": {
> "status": "active"
> }
> }
> }
> ```
> **Example: subscription.plan\_changed payload**
>
> ```json theme={null}
> {
> "id": "b9c2e1f0-7d3a-4b8e-a456-1f2a3b4c5d6e",
> "type": "subscription.plan_changed",
> "created_at": "2026-03-04T11:53:12Z",
> "data": {
> "object": {
> "id": "d1284180-beba-465a-b756-9a300324245e",
> "object": "subscription",
> "status": "active",
> "plan": {
> "name": "Pro",
> "version": 4,
> "identifier": "pro"
> },
> "product": {
> "id": "988dba89-0a96-4cb5-870a-34810011c1f1",
> "name": "demo"
> },
> "amount": "29.00",
> "amount_units": 2900,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-02-26",
> "end_date": null,
> "billing_period_start_time": "2026-02-26T05:25:11Z",
> "billing_period_end_time": "2026-03-26T05:25:11Z",
> "trial_start": "2026-02-26T05:25:11Z",
> "trial_end": "2026-03-12T05:25:11Z",
> "customer": {
> "id": "798e663f-2fe9-43d7-879f-2549263e20d1",
> "name": "Geo",
> "email": "geo@example.com",
> "customer_id": "geo123",
> "billing_address": {}
> },
> "features": null,
> "organization": "5d0bec80-a7c1-41ae-bd24-ea9228500586",
> "created_on": "2026-03-04T11:53:12Z",
> "modified_on": "2026-03-04T11:53:14Z"
> },
> "previous_attributes": {
> "id": "065ee4e2-b643-4f78-bac0-9bd4afcba963",
> "object": "subscription",
> "status": "active",
> "plan": {
> "name": "Enterprise",
> "version": 1,
> "identifier": "enterprise"
> },
> "product": {
> "id": "988dba89-0a96-4cb5-870a-34810011c1f1",
> "name": "demo"
> },
> "amount": "99.00",
> "amount_units": 9900,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-02-26",
> "end_date": null,
> "billing_period_start_time": "2026-02-26T05:25:11Z",
> "billing_period_end_time": "2026-03-26T05:25:11Z",
> "trial_start": "2026-02-26T05:25:11Z",
> "trial_end": "2026-03-12T05:25:11Z",
> "customer": {
> "id": "798e663f-2fe9-43d7-879f-2549263e20d1",
> "name": "Geo",
> "email": "geo@example.com",
> "customer_id": "geo123",
> "billing_address": {}
> },
> "features": null,
> "organization": "5d0bec80-a7c1-41ae-bd24-ea9228500586",
> "created_on": "2026-03-04T11:29:19Z",
> "modified_on": "2026-03-04T11:29:23Z"
> }
> }
> }
> ```
> **Example: subscription.paused payload**
>
> ```json theme={null}
> {
> "id": "c4d1a2b3-9e8f-4a7b-b123-4c5d6e7f8a9b",
> "type": "subscription.paused",
> "created_at": "2026-09-30T10:00:00Z",
> "data": {
> "object": {
> "id": "d1284180-beba-465a-b756-9a300324245e",
> "object": "subscription",
> "status": "paused",
> "paused_at": "2026-09-30T10:00:00Z",
> "pause_resumes_at": "2026-12-31T23:00:00Z",
> "plan": {
> "name": "Pro",
> "version": 4,
> "identifier": "pro"
> },
> "product": {
> "id": "988dba89-0a96-4cb5-870a-34810011c1f1",
> "name": "demo"
> },
> "amount": "29.00",
> "amount_units": 2900,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-02-26",
> "end_date": null,
> "billing_period_start_time": "2026-09-26T05:25:11Z",
> "billing_period_end_time": "2026-10-26T05:25:11Z",
> "customer": {
> "id": "798e663f-2fe9-43d7-879f-2549263e20d1",
> "name": "Geo",
> "email": "geo@example.com",
> "customer_id": "geo123",
> "billing_address": {}
> },
> "organization": "5d0bec80-a7c1-41ae-bd24-ea9228500586",
> "created_on": "2026-02-26T05:25:11Z",
> "modified_on": "2026-09-30T10:00:00Z"
> }
> }
> }
> ```
> **Example: subscription.resumed payload**
>
> ```json theme={null}
> {
> "id": "e5f6a7b8-1c2d-4e3f-a456-7b8c9d0e1f2a",
> "type": "subscription.resumed",
> "created_at": "2026-12-31T23:00:00Z",
> "data": {
> "object": {
> "id": "d1284180-beba-465a-b756-9a300324245e",
> "object": "subscription",
> "status": "active",
> "paused_at": null,
> "pause_resumes_at": null,
> "plan": {
> "name": "Pro",
> "version": 4,
> "identifier": "pro"
> },
> "product": {
> "id": "988dba89-0a96-4cb5-870a-34810011c1f1",
> "name": "demo"
> },
> "amount": "29.00",
> "amount_units": 2900,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-02-26",
> "end_date": null,
> "billing_period_start_time": "2026-12-31T23:00:00Z",
> "billing_period_end_time": "2027-01-31T23:00:00Z",
> "customer": {
> "id": "798e663f-2fe9-43d7-879f-2549263e20d1",
> "name": "Geo",
> "email": "geo@example.com",
> "customer_id": "geo123",
> "billing_address": {}
> },
> "organization": "5d0bec80-a7c1-41ae-bd24-ea9228500586",
> "created_on": "2026-02-26T05:25:11Z",
> "modified_on": "2026-12-31T23:00:00Z"
> }
> }
> }
> ```
> **Example: subscription.trial\_will\_end payload**
>
> ```json theme={null}
> {
> "id": "7c6d5e4f-3b2a-4190-8e7d-6c5b4a3f2e1d",
> "type": "subscription.trial_will_end",
> "created_at": "2026-08-08T05:25:34Z",
> "data": {
> "object": {
> "id": "a22f1b2a-b922-4a28-9b0e-75e826988b4b",
> "object": "subscription",
> "status": "trialing",
> "plan": {
> "name": "Pro",
> "version": 1,
> "identifier": "pro"
> },
> "product": {
> "id": "b4ea7e75-5dbe-4b3b-96e0-9a31dfe5a600",
> "name": "Acme Analytics"
> },
> "amount": "21.24",
> "amount_units": 2124,
> "currency": "USD",
> "recurrence": "1 month",
> "start_date": "2026-08-01",
> "end_date": null,
> "billing_period_start_time": "2026-08-01T05:25:33Z",
> "billing_period_end_time": "2026-08-31T05:25:33Z",
> "trial_start": "2026-08-01T05:25:33Z",
> "trial_end": "2026-08-11T05:25:33Z",
> "customer": {
> "id": "1bb69d0f-39f8-4db8-aace-e003d6e5f3ed",
> "name": "Geo Jacob",
> "email": "geo@example.com",
> "customer_id": "1",
> "billing_address": {
> "city": "Bangalore",
> "line1": null,
> "line2": null,
> "state": "Karnataka",
> "country": "IN",
> "postal_code": "560001"
> }
> },
> "features": null,
> "organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c",
> "created_on": "2026-08-01T05:25:34Z",
> "modified_on": "2026-08-01T05:25:34Z"
> }
> }
> }
> ```
>
> `data.object` uses the same subscription payload shape as `subscription.created`/`subscription.updated`; the trial's remaining time is in `trial_end`. Kelviq sends this once, a few days before `trial_end`. It's skipped if the subscription has already converted to `active` or has no trial days left.
> **Example: feature.usage\_alert payload**
>
> ```json theme={null}
> {
> "id": "575a1aa4-3414-4e08-b4ad-6bfd3e96322d",
> "type": "feature.usage_alert",
> "created_at": "2026-05-18T18:48:59Z",
> "data": {
> "object": {
> "id": "a1c88c9d-19cf-48cc-b194-6cc6ebb356ee",
> "object": "feature_usage_alert",
> "feature": {
> "id": "245d745f-28ca-4856-81fe-1e1f5c6c7ebd",
> "name": "API calls",
> "identifier": "api-calls",
> "feature_type": "METER"
> },
> "customer": {
> "id": "d2b6c9ac-bcd5-4e59-8c7e-b6472485e112",
> "name": "Geo",
> "email": "geo@example.com",
> "customer_id": "fcec7a06c7484584b8a4d92711bfe528",
> "billing_address": {
> "city": null,
> "line1": null,
> "line2": null,
> "state": null,
> "country": "IN",
> "postal_code": "680121"
> }
> },
> "usage_limit": 5,
> "current_usage": 5,
> "threshold_type": "PERCENTAGE",
> "threshold_value": 90,
> "period_start_time": "2026-05-18T00:00:00Z",
> "period_end_time": null,
> "subscription_id": "137e4652-5540-4a3b-9bce-fa393b028539",
> "organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c",
> "created_on": "2026-05-18T17:57:16Z",
> "modified_on": "2026-05-18T17:57:17Z"
> }
> }
> }
> ```
> **Example: invoice.created payload**
>
> ```json theme={null}
> {
> "id": "2f31925f-10fc-41eb-8cb9-3cdf2b4e9e29",
> "type": "invoice.created",
> "created_at": "2026-04-02T05:56:33Z",
> "data": {
> "object": {
> "id": "INV-20260402055633-FCM4B",
> "object": "invoice",
> "status": "OPEN",
> "paid_at": null,
> "amount_total": "40",
> "amount_total_units": 4000,
> "currency": "USD",
> "due_date": null,
> "attempt_count": 0,
> "next_payment_attempt": null,
> "failure_details": null,
> "payment_link": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
> "order_id": null,
> "customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "customer": {
> "id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "created_on": "2026-04-02T05:56:33Z",
> "modified_on": "2026-04-02T05:56:33Z"
> }
> }
> }
> ```
> **Example: invoice.paid payload**
>
> ```json theme={null}
> {
> "id": "9d2c7e54-3f1b-4a8c-9e6d-2b5f8e1a4c7b",
> "type": "invoice.paid",
> "created_at": "2026-04-02T06:00:00Z",
> "data": {
> "object": {
> "id": "INV-20260402055633-FCM4B",
> "object": "invoice",
> "status": "PAID",
> "paid_at": "2026-04-02T06:00:00Z",
> "amount_total": "40",
> "amount_total_units": 4000,
> "currency": "USD",
> "due_date": null,
> "attempt_count": 1,
> "next_payment_attempt": null,
> "failure_details": null,
> "payment_link": null,
> "order_id": null,
> "customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "customer": {
> "id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "created_on": "2026-04-02T05:56:33Z",
> "modified_on": "2026-04-02T06:00:00Z"
> },
> "previous_attributes": {
> "status": "OPEN",
> "paid_at": null
> }
> }
> }
> ```
> **Example: invoice.payment\_failed payload**
>
> ```json theme={null}
> {
> "id": "1b8b128e-31c8-48b2-9d0b-f477ce543d58",
> "type": "invoice.payment_failed",
> "created_at": "2026-08-01T10:14:22Z",
> "data": {
> "object": {
> "id": "INV-20260801101420-Q7M2P",
> "object": "invoice",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "status": "PAYMENT_FAILED",
> "customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "customer": {
> "id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "product": {
> "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
> "name": "Acme Analytics"
> },
> "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
> "order_id": null,
> "payment_link": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
> "amount_total": "40",
> "amount_total_units": 4000,
> "currency": "USD",
> "paid_at": null,
> "due_date": "2026-08-01T10:14:22Z",
> "attempt_count": 1,
> "next_payment_attempt": "2026-08-04T10:14:22Z",
> "failure_details": {
> "code": "card_declined",
> "message": "Your card was declined.",
> "payment_method_type": "card"
> },
> "created_on": "2026-08-01T10:14:20Z",
> "modified_on": "2026-08-01T10:14:22Z"
> }
> }
> }
> ```
>
> `attempt_count`, `next_payment_attempt`, and `payment_link` are also included on `invoice.created` and `invoice.paid` payloads. `failure_details` (with `code`, `message`, and `payment_method_type`) describes the most recent failed attempt and is `null` once the invoice moves past that attempt (e.g. a later `invoice.paid` for the same invoice). `payment_link` is `null` whenever the invoice isn't currently payable (e.g. already paid).
> **Example: refund.created payload**
>
> ```json theme={null}
> {
> "id": "6e76547b-9b6b-4504-af36-c8f646fa91fe",
> "type": "refund.created",
> "created_at": "2026-04-02T05:41:21Z",
> "data": {
> "object": {
> "id": "ca435ba3-d951-472d-a836-370787df3026",
> "object": "refund",
> "status": "PROCESSING",
> "amount": "20.0",
> "amount_units": 2000,
> "currency": "USD",
> "reason": "REQUESTED_BY_CUSTOMER",
> "order_id": "ORD-20260402042513-8M80C",
> "customer": {
> "id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "created_on": "2026-04-02T05:41:21Z",
> "modified_on": "2026-04-02T05:41:21Z"
> }
> }
> }
> ```
> **Example: refund.updated payload**
>
> ```json theme={null}
> {
> "id": "e2b8d4f1-6a3c-4f9e-b7d2-9c1a5e3f8b04",
> "type": "refund.updated",
> "created_at": "2026-04-02T05:41:30Z",
> "data": {
> "object": {
> "id": "ca435ba3-d951-472d-a836-370787df3026",
> "object": "refund",
> "status": "SUCCEEDED",
> "amount": "20.0",
> "amount_units": 2000,
> "currency": "USD",
> "reason": "REQUESTED_BY_CUSTOMER",
> "order_id": "ORD-20260402042513-8M80C",
> "customer": {
> "id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "created_on": "2026-04-02T05:41:21Z",
> "modified_on": "2026-04-02T05:41:30Z"
> }
> }
> }
> ```
> **Example: payment\_method.created payload**
>
> ```json theme={null}
> {
> "id": "7f9c9a3e-2b41-4b7a-9d2e-5c8f1a6b3d4e",
> "type": "payment_method.created",
> "created_at": "2026-04-02T06:12:04Z",
> "data": {
> "object": {
> "id": 482,
> "object": "payment_method",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "customer_id": "geo-jacob",
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "method_type": "card",
> "method_data": {
> "brand": "visa",
> "last4": "4242",
> "exp_month": 12,
> "exp_year": 2029,
> "funding": "credit",
> "country": "US"
> },
> "is_default": true,
> "status": "succeeded"
> }
> }
> }
> ```
> **Example: payment\_method.updated payload**
>
> ```json theme={null}
> {
> "id": "b1d4e5f6-3c72-4a9b-8e1d-6f2a9c4b7e8d",
> "type": "payment_method.updated",
> "created_at": "2026-04-02T06:15:47Z",
> "data": {
> "object": {
> "id": 482,
> "object": "payment_method",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "customer_id": "geo-jacob",
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "method_type": "card",
> "method_data": {
> "brand": "visa",
> "last4": "4242",
> "exp_month": 12,
> "exp_year": 2029,
> "funding": "credit",
> "country": "US"
> },
> "is_default": true,
> "status": "succeeded"
> }
> }
> }
> ```
> **Example: payment\_method.deleted payload**
>
> ```json theme={null}
> {
> "id": "e3a2b1c0-9d8e-47f6-b5a4-1c2d3e4f5a6b",
> "type": "payment_method.deleted",
> "created_at": "2026-04-02T06:20:12Z",
> "data": {
> "object": {
> "id": 482,
> "object": "payment_method",
> "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
> "customer_id": "geo-jacob",
> "customer": {
> "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
> "name": "Geo Jacob",
> "email": "geojacob@example.com",
> "customer_id": "geo-jacob",
> "billing_address": {
> "line1": null,
> "line2": null,
> "city": null,
> "state": null,
> "postal_code": "680121",
> "country": "IN"
> }
> },
> "method_type": "card",
> "method_data": {
> "brand": "visa",
> "last4": "4242",
> "exp_month": 12,
> "exp_year": 2029,
> "funding": "credit",
> "country": "US"
> },
> "is_default": false,
> "status": "succeeded"
> }
> }
> }
> ```
***
## Verifying Signatures
> [!WARNING]
>
> Always verify the signature before processing a webhook. Skipping verification exposes your endpoint to spoofed requests from third parties.
Kelviq signs every request using **HMAC-SHA256**. To verify a request:
1. Read the `webhook-id` and `webhook-timestamp` headers.
2. Construct the signed string by concatenating: `{webhook-id}.{webhook-timestamp}.{raw-request-body}` (joined with `.`)
3. Compute HMAC-SHA256 over the signed string using your endpoint's signing secret as the key.
4. Compare the hex digest to the signature in the `webhook-signature` header (strip the `v1,` prefix before comparing).
5. Reject the request if the signatures do not match.
> [!NOTE]
>
> The raw request body must be used exactly as received — before any JSON parsing. The compact JSON serialization (no spaces) is what Kelviq sends and signs.
Optionally, also check that `webhook-timestamp` is within a few minutes of your server's current time to defend against replay attacks.
***
## Code Examples
> [!NOTE]
>
> Use `express.raw()` (not `express.json()`) in Node.js so that `req.body` contains the unmodified request bytes. Parsing the body before verification will break the signature check. On a framework built on the Fetch API (Next.js route handlers, Hono, Remix, Cloudflare Workers), read the body with `await request.text()` and take each header with `request.headers.get(...)`, since `request.headers` is a `Headers` object rather than a plain object.
```javascript Node.js theme={null}
const crypto = require('crypto');
function verifyWebhook(req, signingSecret) {
const webhookId = req.headers['webhook-id'];
const webhookTimestamp = req.headers['webhook-timestamp'];
const webhookSignature = req.headers['webhook-signature'];
if (!webhookId || !webhookTimestamp || !webhookSignature) {
throw new Error('Missing required webhook headers');
}
// Defend against replay attacks (5-minute tolerance)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(webhookTimestamp, 10)) > 300) {
throw new Error('Webhook timestamp is too old');
}
// Reconstruct the signed payload
const rawBody = req.body; // must be the raw Buffer/string, not parsed JSON
const signedPayload = `${webhookId}.${webhookTimestamp}.${rawBody}`;
// Compute HMAC-SHA256
const expectedSignature = crypto
.createHmac('sha256', signingSecret)
.update(signedPayload, 'utf8')
.digest('hex');
// Strip the "v1," prefix from the header value
const [, receivedSignature] = webhookSignature.split(',');
if (!crypto.timingSafeEqual(
Buffer.from(expectedSignature, 'hex'),
Buffer.from(receivedSignature, 'hex')
)) {
throw new Error('Webhook signature mismatch');
}
return JSON.parse(rawBody);
}
// Express handler example
app.post('/webhooks/kelviq', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = verifyWebhook(req, process.env.KELVIQ_WEBHOOK_SECRET);
} catch (err) {
console.error('Webhook verification failed:', err.message);
return res.status(400).send('Bad Request');
}
switch (event.type) {
case 'subscription.created':
console.log('New subscription:', event.data.object.id);
break;
case 'invoice.paid':
console.log('Invoice paid:', event.data.object.id);
break;
default:
console.log('Unhandled event type:', event.type);
}
res.status(200).json({ received: true });
});
```
```python Python theme={null}
import hashlib
import hmac
import json
import time
from flask import Flask, request, abort
app = Flask(__name__)
SIGNING_SECRET = "kq_whsec_your_secret_here" # load from environment
def verify_webhook(payload_bytes: bytes, webhook_id: str, webhook_timestamp: str, webhook_signature: str) -> dict:
# Defend against replay attacks (5-minute tolerance)
now = int(time.time())
if abs(now - int(webhook_timestamp)) > 300:
raise ValueError("Webhook timestamp is too old")
# Reconstruct the signed payload (body must be the raw bytes decoded as utf-8)
signed_payload = f"{webhook_id}.{webhook_timestamp}.{payload_bytes.decode('utf-8')}"
# Compute HMAC-SHA256
expected_signature = hmac.new(
SIGNING_SECRET.encode("utf-8"),
signed_payload.encode("utf-8"),
hashlib.sha256,
).hexdigest()
# Strip the "v1," prefix from the header value
_, received_signature = webhook_signature.split(",", 1)
if not hmac.compare_digest(expected_signature, received_signature):
raise ValueError("Webhook signature mismatch")
return json.loads(payload_bytes)
@app.route("/webhooks/kelviq", methods=["POST"])
def handle_webhook():
webhook_id = request.headers.get("webhook-id")
webhook_timestamp = request.headers.get("webhook-timestamp")
webhook_signature = request.headers.get("webhook-signature")
try:
event = verify_webhook(request.get_data(), webhook_id, webhook_timestamp, webhook_signature)
except ValueError as e:
print(f"Webhook verification failed: {e}")
abort(400)
event_type = event.get("type")
if event_type == "subscription.created":
print("New subscription:", event["data"]["object"]["id"])
elif event_type == "invoice.paid":
print("Invoice paid:", event["data"]["object"]["id"])
else:
print("Unhandled event type:", event_type)
return {"received": True}, 200
```
```go Go theme={null}
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"math"
"net/http"
"strconv"
"strings"
"time"
)
const signingSecret = "kq_whsec_your_secret_here" // load from environment
type WebhookEvent struct {
ID string `json:"id"`
Type string `json:"type"`
CreatedAt string `json:"created_at"`
Data json.RawMessage `json:"data"`
}
func verifyWebhook(body []byte, webhookID, webhookTimestamp, webhookSignature string) (*WebhookEvent, error) {
// Defend against replay attacks (5-minute tolerance)
ts, err := strconv.ParseInt(webhookTimestamp, 10, 64)
if err != nil {
return nil, errors.New("invalid webhook-timestamp header")
}
if math.Abs(float64(time.Now().Unix()-ts)) > 300 {
return nil, errors.New("webhook timestamp is too old")
}
// Reconstruct the signed payload
signedPayload := fmt.Sprintf("%s.%s.%s", webhookID, webhookTimestamp, string(body))
// Compute HMAC-SHA256
mac := hmac.New(sha256.New, []byte(signingSecret))
mac.Write([]byte(signedPayload))
expectedSig := hex.EncodeToString(mac.Sum(nil))
// Strip the "v1," prefix from the header value
parts := strings.SplitN(webhookSignature, ",", 2)
if len(parts) != 2 {
return nil, errors.New("malformed webhook-signature header")
}
receivedSig := parts[1]
expectedBytes, _ := hex.DecodeString(expectedSig)
receivedBytes, _ := hex.DecodeString(receivedSig)
if !hmac.Equal(expectedBytes, receivedBytes) {
return nil, errors.New("webhook signature mismatch")
}
var event WebhookEvent
if err := json.Unmarshal(body, &event); err != nil {
return nil, fmt.Errorf("failed to parse webhook body: %w", err)
}
return &event, nil
}
func webhookHandler(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "cannot read body", http.StatusBadRequest)
return
}
defer r.Body.Close()
event, err := verifyWebhook(
body,
r.Header.Get("webhook-id"),
r.Header.Get("webhook-timestamp"),
r.Header.Get("webhook-signature"),
)
if err != nil {
http.Error(w, "Bad Request: "+err.Error(), http.StatusBadRequest)
return
}
switch event.Type {
case "subscription.created":
fmt.Println("New subscription:", event.ID)
case "invoice.paid":
fmt.Println("Invoice paid:", event.ID)
default:
fmt.Println("Unhandled event type:", event.Type)
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
w.Write([]byte(`{"received":true}`))
}
func main() {
http.HandleFunc("/webhooks/kelviq", webhookHandler)
http.ListenAndServe(":8080", nil)
}
```
***
## Best Practices
* **Return `2xx` fast.** Acknowledge the webhook immediately and process it asynchronously. Long-running handlers increase the risk of timeouts and duplicate retries.
* **Make handlers idempotent.** The same event may be delivered more than once. Use the top-level event `id` or the `webhook-id` header as the deduplication key.
* **Validate the timestamp.** Reject requests where `webhook-timestamp` is more than 5 minutes from your server's clock to prevent replay attacks.
* **Use `hmac.compare_digest` / `hmac.Equal` / `crypto.timingSafeEqual`.** Constant-time comparison prevents timing side-channel attacks.
* **Store the raw body before parsing.** Signature verification operates on the raw bytes, not the deserialized object.
***
## Need Help?
* Email us at **[hi@kelviq.com](mailto:hi@kelviq.com)**
* [Book a demo](https://cal.com/alok-vats-fkpnc9/30min)
# Acceptable Use Policy
Source: https://docs.kelviq.com/legal/approved-prohibited-policy
Kelviq's policy on approved, restricted, and prohibited business categories
> [!NOTE]
>
> **Version 1.0** | Effective Date: February 11, 2026
## 1. Purpose
Kelviq, Inc. ("Kelviq") operates as a Merchant of Record (MoR) for digital product sellers. As the MoR, Kelviq is legally and financially responsible for every transaction processed through the platform. This policy defines the types of businesses, products, and activities that are approved, restricted, or prohibited on the Kelviq platform.
This policy is designed to ensure compliance with applicable laws, regulations, payment network rules (including Visa and Mastercard operating regulations), U.S. sanctions laws (OFAC), and the terms of our payment processing agreements with Stripe, Inc.
This policy is incorporated by reference into the Kelviq Seller Master Service Agreement and applies to all Sellers on the platform.
## 2. Approved Business Categories
Kelviq is designed for digital products and software. The following business categories are approved for the platform:
### 2.1 SaaS and Software
* Business-to-business (B2B) and business-to-consumer (B2C) web applications
* Desktop software and browser extensions
* AI tools and AI-powered software products (subject to additional review per Section 4)
* Developer tools, APIs, and SDKs
### 2.2 Digital Downloads
* E-books and digital publications (PDF, EPUB)
* Design templates, fonts, and design assets
* Audio files, music, and sound effects (original or properly licensed)
* Video courses and educational content
* Photography presets, filters, and digital art
### 2.3 Membership and Subscription Content
* Paid newsletters and research publications
* Membership communities with gated content
* Online course platforms with recurring access
### 2.4 Professional Services (Limited)
Professional services are approved only when sold as add-ons to a software product. Examples include setup fees, priority support packages, and onboarding assistance for a software product. Standalone manual services (consulting, coaching, agency work) are not approved.
> [!NOTE]
>
> **Approval criteria:** The product must be digital, owned by the Seller (or properly licensed), and deliverable immediately upon purchase.
## 3. Fundamental Platform Limitations
The following categories are not supported on the Kelviq platform under any circumstances. These limitations are inherent to our MoR model and cannot be waived.
| Limitation | Description |
| - | - |
| **Digital only** | Kelviq cannot support physical goods, shipping, logistics, or any product that requires physical delivery. |
| **No manual services** | Kelviq cannot support 1-on-1 coaching, consulting, freelancing, or agency services where the primary deliverable is manual labor (not a digital product). |
| **No marketplace or resale** | Sellers must be the original creator or licensed distributor. Sellers cannot use Kelviq to process payments for other unverified third-party sellers. |
## 4. Prohibited Business Categories
The following categories are strictly prohibited. Kelviq will not approve accounts in these categories, and any existing account found to be operating in a prohibited category will be suspended immediately. This list is aligned with Stripe's prohibited business list and applicable card network rules.
### 4.1 Illegal, Deceptive, or Harmful Content
> [!WARNING]
>
> The following are strictly prohibited:
* Products or services that are illegal in the United States or the Buyer's jurisdiction
* Content that infringes on third-party intellectual property, copyrights, trademarks, or patents (including pirated software, stolen e-books, cracked license keys)
* Hate speech or content promoting violence, self-harm, or discrimination
* Deceptive marketing, fake testimonials, or unrealistic income or results claims
* Low-value exploitative content (including mass-generated AI content with minimal substance sold at inflated prices)
* Identity services, fake identification documents, or academic cheating services
* Multi-level marketing (MLM) or pyramid scheme products
### 4.2 Financial and Legal Services
* Investment advice, trading signals, or financial planning services
* Cryptocurrency sales, token sales, or NFT minting/trading
* Lending services, debt collection, or money transmission
* Gambling, betting, lotteries, or games of chance (including fantasy sports with entry fees)
* Legal, tax, or accounting advice as a service
* Donation processing where no specific product is delivered
* Services designed to help others evade taxes, mask identity, or bypass financial regulations
### 4.3 Adult Content and Regulated Industries
* Explicitly sexual content (videos, images, text), whether real or AI-generated
* "AI Girlfriend/Boyfriend" services, NSFW chatbots, or sexual companion services
* Content related to OnlyFans management or adult content distribution
* Alcohol, tobacco, vaping products, e-cigarettes
* Drugs, drug paraphernalia, or controlled substances
* Firearms, ammunition, explosives, or combat/weapons training
* Prescription drugs, unverified medical/wellness supplements, or unapproved health claims
### 4.4 Technology and Platform Abuse
* **Spam tools:** mass cold email software, lead scraping tools, bulk SMS/WhatsApp senders
* **Hacking tools:** software designed to gain unauthorized access to systems, networks, or accounts
* **Cheating tools:** software designed to cheat in games or bypass software licensing
* **Circumvention tools:** services that bypass API rate limits, platform rules, or geo-restrictions (IP cloaking, proxy tools for evasion)
* **Surveillance technology:** keyloggers, stalkerware, or tools that enable unauthorized monitoring of individuals
* Counterfeit goods or unauthorized replicas of branded products
### 4.5 Telemarketing and Debt Collection
* Telemarketing services, including outbound call centers and robocall operations
* Debt collection agencies or services
* Lead generation services that involve unsolicited outbound communication (phone, SMS, or email)
### 4.6 Other Prohibited Activities
* Money laundering, structuring, or processing transactions that are not genuine product sales
* Terrorist financing or transactions with designated persons on sanctions lists
* Activities that violate U.S. sanctions (OFAC) or export control regulations
* Transactions designed to test or exploit the payment system (carding, card testing)
## 5. Restricted Business Categories
The following categories are not automatically prohibited but are considered high-risk. Accounts in these categories require additional review by the Kelviq compliance team. Approval is not guaranteed and may be subject to conditions such as reserve requirements, payout holds, or additional monitoring.
### 5.1 AI-Powered Products and Services
AI tools that generate text, images, voice, video, or other content require review to verify:
* The product has appropriate safeguards against generating harmful, deceptive, adult, or illegal content
* The product does not facilitate deepfakes, impersonation, or disinformation
* The product's marketing accurately represents its capabilities
* The Seller has content moderation policies in place
### 5.2 Marketing and Outreach Tools
Some marketing tools may be approved, but the following require additional review:
* Email marketing tools (must have anti-spam compliance, opt-in verification, and unsubscribe functionality)
* Social media automation tools (must comply with platform terms of service)
* Lead generation tools (must not facilitate scraping or unauthorized data collection)
### 5.3 Pre-orders and Paid Waitlists
Pre-orders are generally not approved due to the high chargeback risk for an MoR. In rare cases, exceptions may be made for established creators with a proven track record. If approved, funds will be held in reserve until the product is verifiably delivered.
### 5.4 High-Value Digital Products
Products priced above \$500 per transaction may require additional review due to elevated chargeback risk.
## 6. Prohibited Countries and Sanctions Compliance
Kelviq is a U.S. company and is required to comply with U.S. sanctions laws administered by the Office of Foreign Assets Control (OFAC). Kelviq is strictly prohibited from doing business with any individual or entity located in the following countries and regions:
> [!WARNING]
>
> **Sanctioned Countries and Regions:**
>
> * North Korea
> * Iran
> * Cuba
> * Syria
> * Russia
> * Belarus
> * Crimea, Donetsk, and Luhansk regions of Ukraine
Kelviq also screens all Sellers against the OFAC Specially Designated Nationals (SDN) list and other applicable sanctions lists. Sellers identified on any sanctions list will be immediately blocked from the platform.
This list is subject to change based on updates to U.S. sanctions regulations. Sellers are required to notify Kelviq immediately if they become aware of any sanctions-related issues affecting their account.
## 7. Supported Payout Countries
Kelviq supports businesses registered in 90+ countries for payouts. You can receive payouts in your local bank account in currencies including USD, EUR, GBP, CAD, AUD, INR, and more.
| | | |
| :- | :- | :- |
| 🇦🇱 Albania | 🇦🇬 Antigua & Barbuda | 🇦🇷 Argentina |
| 🇦🇲 Armenia | 🇦🇺 Australia | 🇦🇹 Austria |
| 🇧🇸 Bahamas | 🇧🇭 Bahrain | 🇧🇪 Belgium |
| 🇧🇯 Benin | 🇧🇴 Bolivia | 🇧🇦 Bosnia & Herzegovina |
| 🇧🇼 Botswana | 🇧🇳 Brunei | 🇧🇬 Bulgaria |
| 🇰🇭 Cambodia | 🇨🇦 Canada | 🇨🇱 Chile |
| 🇨🇴 Colombia | 🇨🇷 Costa Rica | 🇨🇮 Côte d'Ivoire |
| 🇨🇾 Cyprus | 🇨🇿 Czech Republic | 🇩🇰 Denmark |
| 🇩🇴 Dominican Republic | 🇪🇨 Ecuador | 🇪🇬 Egypt |
| 🇸🇻 El Salvador | 🇪🇪 Estonia | 🇪🇹 Ethiopia |
| 🇫🇮 Finland | 🇫🇷 France | 🇬🇲 Gambia |
| 🇩🇪 Germany | 🇬🇭 Ghana | 🇬🇷 Greece |
| 🇬🇹 Guatemala | 🇬🇾 Guyana | 🇭🇰 Hong Kong |
| 🇭🇺 Hungary | 🇮🇳 India | 🇮🇸 Iceland |
| 🇮🇪 Ireland | 🇮🇱 Israel | 🇮🇹 Italy |
| 🇯🇲 Jamaica | 🇯🇵 Japan | 🇯🇴 Jordan |
| 🇰🇪 Kenya | 🇰🇼 Kuwait | 🇱🇻 Latvia |
| 🇱🇹 Lithuania | 🇱🇺 Luxembourg | 🇲🇴 Macao SAR China |
| 🇲🇬 Madagascar | 🇲🇹 Malta | 🇲🇺 Mauritius |
| 🇲🇽 Mexico | 🇲🇩 Moldova | 🇲🇨 Monaco |
| 🇲🇳 Mongolia | 🇲🇦 Morocco | 🇳🇦 Namibia |
| 🇳🇱 Netherlands | 🇳🇿 New Zealand | 🇳🇬 Nigeria |
| 🇲🇰 North Macedonia | 🇳🇴 Norway | 🇴🇲 Oman |
| 🇵🇰 Pakistan | 🇵🇦 Panama | 🇵🇾 Paraguay |
| 🇵🇪 Peru | 🇵🇭 Philippines | 🇵🇱 Poland |
| 🇵🇹 Portugal | 🇶🇦 Qatar | 🇷🇴 Romania |
| 🇷🇼 Rwanda | 🇸🇦 Saudi Arabia | 🇸🇳 Senegal |
| 🇷🇸 Serbia | 🇸🇬 Singapore | 🇸🇰 Slovakia |
| 🇸🇮 Slovenia | 🇿🇦 South Africa | 🇰🇷 South Korea |
| 🇪🇸 Spain | 🇱🇰 Sri Lanka | 🇱🇨 St. Lucia |
| 🇸🇪 Sweden | 🇨🇭 Switzerland | 🇹🇼 Taiwan |
| 🇹🇿 Tanzania | 🇹🇭 Thailand | 🇹🇹 Trinidad & Tobago |
| 🇹🇳 Tunisia | 🇹🇷 Turkey | 🇦🇪 United Arab Emirates |
| 🇬🇧 United Kingdom | 🇺🇸 United States | 🇺🇾 Uruguay |
| 🇺🇿 Uzbekistan | 🇻🇳 Vietnam | |
> [!NOTE]
>
> This list is determined by Stripe and is subject to change. Sellers located in countries not on the supported list cannot complete onboarding or receive payouts.
## 8. Enforcement and Monitoring
Kelviq continuously monitors Seller accounts after approval to detect and prevent violations of this policy. Monitoring includes:
### 8.1 Ongoing Monitoring
* Transaction pattern analysis for unusual activity, velocity changes, or suspicious behavior
* Refund rate monitoring (accounts exceeding 10% refund rates may be reviewed)
* Chargeback rate monitoring (accounts exceeding 0.75% chargeback rates will be reviewed, accounts exceeding 1% may be suspended)
* Product listing review (periodic review of product descriptions and content for accuracy and compliance)
* Customer complaints and fraud reports
### 8.2 Enforcement Actions
If a Seller is found to be in violation of this policy, Kelviq may take one or more of the following actions:
1. Issuing a warning and requesting immediate corrective action
2. Imposing a reserve or payout hold on the Seller's account
3. Suspending the Seller's ability to process new transactions
4. Terminating the Seller's account
5. Withholding funds to cover potential disputes, chargebacks, or liabilities
6. Reporting the Seller to law enforcement or regulatory authorities where required by law
### 8.3 Appeal Process
Sellers who believe their account was suspended or terminated in error may contact Kelviq at [support@kelviq.com](mailto:support@kelviq.com) to request a review. Kelviq will review the appeal and respond within 10 business days. Kelviq's decision on appeals is final.
## 9. Alignment with Card Network Rules
This policy is designed to be consistent with the prohibited and restricted business categories defined by Stripe, Visa, Mastercard, and other applicable payment networks. In cases where card network rules are more restrictive than this policy, the card network rules will control.
Kelviq regularly reviews updates to card network operating regulations and Stripe's prohibited business list to ensure this policy remains current. If card network rules change, Kelviq may update this policy and notify affected Sellers.
## 10. Policy Updates
Kelviq may update this policy from time to time to reflect changes in law, regulations, card network rules, or Kelviq's business practices. Material changes will be communicated to Sellers with at least 30 days' notice. Continued use of the platform after the effective date of a change constitutes acceptance of the updated policy.
## 11. Contact
If you are unsure whether your product or business is allowed on Kelviq, contact us before launching:
> **Kelviq, Inc.**
>
> 2261 Market Street STE 46163
> San Francisco, CA 94114
>
> Email: [hi@kelviq.com](mailto:hi@kelviq.com)
# Buyer Terms
Source: https://docs.kelviq.com/legal/buyer-terms
Terms and conditions for buyers purchasing through Kelviq
> [!NOTE]
>
> **Effective Date:** December 23, 2025
These Buyer Terms are a contract between you and Kelviq, Inc. ("Kelviq", "we", "us"). By using Kelviq checkout or the customer portal, you agree to these terms.
## 1. Who We Are
> **Kelviq, Inc.**
>
> 2261 Market Street STE 46163
> San Francisco, CA 94114
>
> Email: [support@kelviq.com](mailto:support@kelviq.com)
Kelviq acts as the Merchant of Record for all purchases made through Kelviq checkout. This means your payment is made to Kelviq, and Kelviq issues your receipt or invoice, handles refunds (when approved), and manages disputes and chargebacks. Kelviq's name will appear on your bank or card statement as the merchant for the transaction.
## 2. Who These Terms Cover
These terms apply to buyers who use:
* Kelviq checkout and payment pages
* The Kelviq customer portal (orders, invoices, downloads, license keys, subscriptions, refunds)
## 3. Eligibility
You must be 18 or older to buy through Kelviq. By placing an order, you confirm you are an adult and you have the right to use the payment method.
## 4. Your Order
When you place an order, you agree that:
* The information you provide is accurate (name, email, billing details).
* You are allowed to buy and use the product under your local laws.
* We may decline, cancel, or limit an order if we believe it is suspicious, fraudulent, or not allowed.
## 5. Prices, Currency, and Taxes
* Prices and currency are shown at checkout before you pay.
* If taxes are required (based on location and rules), they will be shown at checkout or included in the total, depending on the product and region.
* If you use discounts, they apply only as shown at checkout.
## 6. Payments
* Kelviq uses Stripe to process payments.
* Kelviq does not store full card numbers on our servers.
* Your bank or payment provider may charge extra fees (example: foreign transaction fees). Those fees are not controlled by Kelviq.
## 7. Statement Descriptor
When you make a purchase through Kelviq, your bank or card statement will show "KELVIQ" (or "KELVIQ\*" followed by a product identifier) as the merchant name. This is because Kelviq is the Merchant of Record for the transaction.
## 8. Digital Delivery and Access
Kelviq delivers digital goods through the customer portal, such as:
* Download links or access links
* License keys
* Order and invoice history
Access and downloads may require you to verify your email using an OTP code.
> [!NOTE]
>
> **Important:** The product itself is created and maintained by the seller. Kelviq handles payment and delivery links, but the seller controls product content, updates, and product support (unless the checkout page says Kelviq provides that support).
## 9. License Keys and Usage Rules
If your purchase includes a license key or similar access token:
* You must keep it secure and not share it unless the product terms allow sharing.
* We may disable a key if we believe it was shared, resold, or misused, or if a payment is reversed (chargeback, reversal, or unpaid invoice).
## 10. Subscriptions
If you buy a subscription:
* Your subscription renews automatically until you cancel.
* Renewal timing and price are shown at checkout or in your portal.
* You can cancel from the customer portal. Cancellation typically takes effect at the end of the current billing period unless stated otherwise at checkout.
* If a renewal payment fails, we will retry the charge. For card payments, access will remain available for up to 2 weeks before the subscription is canceled. For other payment methods, the subscription will be canceled immediately if payment fails.
## 11. Refunds
Unless a different refund policy is displayed at checkout, the default refund window for digital products purchased through Kelviq is **30 days** from the date of purchase. Refunds may also be subject to any additional rules that apply in your country.
**How refunds work:**
* You can request a refund in the customer portal or by emailing [support@kelviq.com](mailto:support@kelviq.com).
* If a refund is approved, it is sent back to the original payment method when possible.
* Some fees may not be refundable if your payment provider keeps them (this varies by method and country).
* We may refuse refund requests that appear abusive, fraudulent, or not allowed by the refund terms or local law.
* For subscription products, refunds apply to the most recent billing period only, unless otherwise required by law.
## 12. Disputes and Chargebacks
If you file a chargeback or payment dispute with your bank:
* We may suspend or remove access to the product while the dispute is open.
* We may ask for details to investigate (example: proof of purchase, order details).
* If the dispute is decided against you, you may lose access and may not be eligible for a refund through Kelviq.
> [!TIP]
>
> If you have a problem, contact [support@kelviq.com](mailto:support@kelviq.com) first. It is usually faster than a bank dispute.
## 13. Fraud Prevention and Order Blocking
We use risk checks to prevent fraud and abuse. This can include automatic decisions that:
* Block a payment
* Require extra verification
* Limit certain transactions
If your payment is blocked by mistake, contact [support@kelviq.com](mailto:support@kelviq.com) and we will review.
## 14. Prohibited Activity
You may not use Kelviq checkout or the customer portal to:
* Break laws or payment network rules
* Attempt fraud, chargeback abuse, or evasion of security checks
* Access digital goods you did not purchase
* Reverse engineer, scrape, or attack our systems
* Use stolen payment methods or unauthorized accounts
> [!WARNING]
>
> We may suspend access or cancel orders if we believe prohibited activity occurred.
## 15. Third Party Products and Seller Responsibility
Products sold through Kelviq come from independent sellers. Unless the checkout page clearly says otherwise:
* The seller is responsible for product content, accuracy, and support.
* Kelviq is not the maker of the product.
If you need product help (bugs, usage, features), the seller is usually the right contact. If you are not sure how to reach them, email [support@kelviq.com](mailto:support@kelviq.com) and we will help route it.
## 16. Service Changes
We may change checkout, portal features, or delivery methods to improve reliability or comply with laws. We may also update these terms. If changes are important, we will update the effective date and may provide notice in the portal or at checkout.
## 17. Warranty Disclaimer
To the fullest extent allowed by law:
* Kelviq provides checkout and portal access "as is" and "as available".
* We do not promise uninterrupted service or that every transaction will succeed.
* We do not make promises about the seller's product quality or fitness for your needs.
> [!NOTE]
>
> Some places do not allow certain disclaimers, so some of the above may not apply to you.
## 18. Limits of Liability
To the fullest extent allowed by law:
* Kelviq is not liable for indirect losses (lost profits, lost data, or business interruption).
* Kelviq's total liability for a claim related to a specific purchase is limited to the amount you paid to Kelviq for that purchase.
> [!NOTE]
>
> Some places do not allow certain limits, so some of the above may not apply to you.
## 19. Termination and Access Removal
We may suspend or end your access to the portal or digital goods if:
* A payment is reversed or not paid.
* You violate these terms.
* We must do so to comply with law or protect users.
You can stop using Kelviq at any time. If you have an account or portal access, you can request help via [support@kelviq.com](mailto:support@kelviq.com).
## 20. Governing Law and Venue
These terms are governed by the laws of California, excluding conflict of law rules. Any dispute must be brought in state or federal courts located in San Francisco, California, unless local law requires another venue.
## 21. Contact
Questions about orders, refunds, or these terms: [support@kelviq.com](mailto:support@kelviq.com)
# Transaction Flow
Source: https://docs.kelviq.com/legal/compliant-user-flow
End-to-end user flow documentation for the Kelviq Merchant of Record platform
## 1. Overview
This document describes the end-to-end user flow for both Sellers and Buyers on the Kelviq platform. Kelviq operates as a Merchant of Record (MoR) for digital product sellers, meaning Kelviq is the legal seller to the Buyer for all transactions processed through Kelviq Checkout.
The flows described below demonstrate how Kelviq clearly identifies itself as the MoR at every touchpoint, ensuring compliance with card network rules and providing transparency to Buyers about who they are transacting with.
## 2. Key Parties
> **Kelviq (Platform/MoR)**
>
> Kelviq, Inc. operates the platform, hosts the checkout experience, processes payments through Stripe, and acts as the Merchant of Record for all transactions. Kelviq appears on Buyer bank statements, issues receipts and invoices, and handles refunds and disputes.
> **Seller (Connected Account)**
>
> The digital product creator who lists products on the platform, sets pricing, and is responsible for product quality, content, and customer support. The Seller receives payouts through a Stripe Express Connected Account after fees and reserves are deducted.
> **Buyer (End Customer)**
>
> The person or entity purchasing a digital product through Kelviq Checkout. The Buyer's payment relationship is with Kelviq as the MoR.
> **Stripe (Payment Processor)**
>
> Stripe, Inc. provides the payment infrastructure. Kelviq uses Stripe Connect with separate charges and transfers. Kelviq's platform Stripe account receives the payment, and a separate transfer is made to the Seller's Connected Account.
## 3. Seller Onboarding Flow
The Seller onboarding flow ensures KYC compliance, business verification, and proper agreement acceptance before any live payments are processed.
**1. Account Creation**
Seller creates an account on Kelviq.
**2. Business & Product Details**
Seller provides business information and product details for review.
**3. Agreement Acceptance**
Seller reviews and accepts the Kelviq Seller Master Service Agreement, which includes acknowledgment of Kelviq's role as MoR.
**4. Stripe Connect Onboarding**
Seller is redirected to Stripe Express onboarding to complete identity verification, business verification, and payout setup.
**5. Kelviq Review**
Kelviq reviews the Seller's products and business against the Approved and Prohibited Business Policy. Accounts may be approved, require additional information, or be declined.
**6. Go Live**
Once approved, the Seller's checkout links are activated and can accept live payments.
## 4. Buyer Purchase Flow
The Buyer purchase flow ensures the Buyer clearly understands that Kelviq is the Merchant of Record at every step of the transaction.
**1. Product Discovery**
Buyer finds the Seller's product through the Seller's website, marketing, or other channels. The Seller's branding is present at this stage.
**2. Checkout Initiation**
Buyer clicks a purchase link and is directed to a Kelviq-hosted checkout page. The checkout page displays Kelviq branding and clearly identifies Kelviq as the Merchant of Record.
**3. Terms Acceptance**
Before completing the purchase, the Buyer is presented with links to the Kelviq Buyer Terms. By completing the purchase, the Buyer agrees to these terms.
**4. Payment**
Buyer enters payment details. The payment is processed by Stripe and received by Kelviq's platform Stripe account.
**5. Receipt**
Buyer receives an email receipt from Kelviq, Inc. The receipt clearly identifies Kelviq as the Merchant of Record, includes Kelviq's contact information, and itemizes the purchase.
**6. Fulfillment**
Buyer receives access to the digital product (download link, license key, or access credentials) through the Kelviq Customer Portal or via email.
**7. Bank Statement**
The charge appears on the Buyer's bank or card statement as "KELVIQ" or "KELVIQ\* \[product identifier]".
## 5. Post-Purchase Flows
### 5.1 Refund Flow
Refunds can be initiated by either the Seller or through Kelviq as the Merchant of Record.
**1. Request**
Buyer requests a refund by contacting the Seller directly (via contact form or email) or by emailing Kelviq at [support@kelviq.com](mailto:support@kelviq.com).
**2. Review & Approval**
The Seller reviews the request and can issue a refund directly through the Seller Dashboard. If the request is made through Kelviq, Kelviq reviews it against the applicable refund policy.
**3. Processing**
Once approved, the refund is processed through Stripe. The refund is issued to the Buyer's original payment method. The refunded amount is deducted from the Seller's balance.
### 5.2 Dispute and Chargeback Flow
Chargebacks and payment disputes are managed by Kelviq as the Merchant of Record.
**1. Notification**
Kelviq receives chargeback notification from Stripe.
**2. Evidence Collection**
Kelviq gathers evidence (receipt, delivery confirmation, terms accepted) and may request additional information from the Seller.
**3. Response**
Kelviq submits the chargeback response to Stripe within required timelines.
**4. Resolution**
If the chargeback is decided in Kelviq's favor, the funds are returned. If decided against Kelviq, the chargeback amount and fees are deducted from the Seller's payout balance per the Seller MSA.
### 5.3 Subscription Management
For subscription products, the following ongoing flow applies:
* Subscription renewals are processed automatically by Kelviq through Stripe
* Renewal receipts are issued by Kelviq, Inc.
* Buyers can manage subscriptions (cancel, update payment method) through the Kelviq Customer Portal
* Cancellation takes effect at the end of the current billing period
* Failed renewal payments are retried by Kelviq. For card payments, access remains available for up to 2 weeks before the subscription is canceled. For other payment methods, the subscription is canceled immediately if payment fails
## 6. MoR Compliance Summary
The following table summarizes where and how Kelviq is identified as the Merchant of Record across all touchpoints.
| Touchpoint | Kelviq Identified as MoR |
| - | - |
| Checkout Page | Yes - Kelviq branding and legal name displayed |
| Payment Form | Yes - Kelviq is the entity processing the payment |
| Buyer Terms Link | Yes - Links to Kelviq Buyer Terms |
| Email Receipt | Yes - Issued by Kelviq, Inc. with contact info |
| Bank Statement | Yes - Descriptor shows "KELVIQ" |
| Customer Portal | Yes - Kelviq-branded portal for orders, downloads, and support |
| Refund Processing | Yes - Refunds issued by Kelviq |
| Dispute Handling | Yes - Kelviq responds to chargebacks |
## 7. Card Network Rule Compliance
Kelviq's user flows are designed to comply with the following card network requirements:
> **Transaction Clarity**
>
> The Buyer clearly understands that the transaction is with Kelviq at every point in the purchase flow. Kelviq's name and branding are visible on the checkout page, receipt, and bank statement.
> **Statement Descriptor Accuracy**
>
> The Statement Descriptor identifies Kelviq as the merchant, preventing Buyer confusion about the source of the charge.
> **Refund and Dispute Handling**
>
> Kelviq manages all refunds and disputes as the MoR, in accordance with card network timelines and procedures.
> **Customer Service Identification**
>
> Buyers are directed to Kelviq ([support@kelviq.com](mailto:support@kelviq.com)) for payment-related issues. Product-specific support is provided by the Seller, with clear disclosure of this division of responsibility in the Buyer Terms.
> **MCC Assignment**
>
> Kelviq assigns appropriate Merchant Category Codes for transactions processed through the platform, in compliance with card network requirements.
## 8. Contact
Questions about this document or Kelviq's compliance program should be directed to:
> **Kelviq, Inc.**
>
> 2261 Market Street STE 46163
> San Francisco, CA 94114
>
> Email: [support@kelviq.com](mailto:support@kelviq.com)
# Seller Agreement
Source: https://docs.kelviq.com/legal/master-service-agreement
Master Service Agreement for sellers using the Kelviq platform
> [!NOTE]
>
> **Effective Date:** February 11, 2026
> **Version:** 1.0
> **Kelviq, Inc.**
>
> 2261 Market Street STE 46163
> San Francisco, CA 94114
>
> Email: [support@kelviq.com](mailto:support@kelviq.com)
## 1. Introduction and Scope
This Seller Master Service Agreement (the "Agreement" or "MSA") is a binding contract between Kelviq, Inc., a Delaware corporation ("Kelviq", "we", "us", or "our"), and the business entity or individual who registers as a seller on the Kelviq platform ("Seller", "you", or "your").
By completing the Kelviq seller onboarding process and accepting this Agreement, you agree to be bound by its terms. If you are accepting on behalf of a company or other legal entity, you represent that you have the authority to bind that entity.
This Agreement governs your use of Kelviq's platform to sell digital products, including Kelviq's role as your Merchant of Record for payment processing, tax compliance, and transaction management.
## 2. Definitions
| Term | Definition |
| - | - |
| **Buyer** | Any end customer who purchases a Product through Kelviq Checkout. |
| **Chargeback** | A payment dispute initiated by a Buyer through their bank, card issuer, or payment method provider. |
| **Connected Account** | The Stripe account created for the Seller as part of the Kelviq onboarding process, used to receive payouts. |
| **Kelviq Checkout** | The hosted checkout experience operated by Kelviq where Buyers complete purchases. |
| **Kelviq Platform** or **Platform** | The Kelviq website, dashboard, APIs, checkout, and all related tools and services. |
| **Merchant of Record** or **MoR** | The entity that is the legal seller in a transaction, appears on the Buyer's bank or card statement, and is responsible for payment processing, receipts, refunds, disputes, and applicable tax obligations. |
| **Net Revenue** | The gross amount collected from a Buyer for a transaction, minus applicable taxes, Kelviq platform fees, payment processing fees, and any refunds or chargebacks. |
| **Payout** | The transfer of Net Revenue from Kelviq to the Seller's Connected Account or bank account. |
| **Platform Fees** | The fees charged by Kelviq for use of the Platform, as described in Section 6 and displayed in the Seller Dashboard. |
| **Product** | Any digital good, software, or subscription listed for sale by the Seller through the Kelviq Platform. |
| **Prohibited Activity** | Any activity described in Section 10 of this Agreement or the Kelviq Approved and Prohibited Business Policy. |
| **Statement Descriptor** | The text that appears on a Buyer's bank or card statement identifying the merchant for a transaction. |
| **Stripe** | Stripe, Inc. and its affiliates, the payment infrastructure provider used by Kelviq. |
## 3. Merchant of Record Relationship
### 3.1 Kelviq as Merchant of Record
For all transactions processed through Kelviq Checkout, Kelviq acts as the Merchant of Record. This means that Kelviq is the legal seller to the Buyer for the purpose of payment processing, receipts, invoices, refunds, disputes, chargebacks, and applicable tax collection and remittance.
Kelviq's name and branding will appear on Buyer bank and card statements, checkout pages, receipts, and invoices. The Statement Descriptor for transactions will identify Kelviq as the merchant.
### 3.2 What the MoR Relationship Means for Sellers
As the MoR, Kelviq takes on the following responsibilities on behalf of the Seller:
* Processing Buyer payments through Kelviq Checkout
* Issuing receipts and invoices to Buyers in Kelviq's name
* Handling payment disputes, chargebacks, and refund requests
* Collecting and remitting applicable sales tax, VAT, or GST where required
* Appearing as the merchant on Buyer bank and card statements
* Complying with payment network rules (Visa, Mastercard, and other applicable networks) for transactions processed through the Platform
> [!NOTE]
>
> The Seller remains responsible for the Product itself, including product quality, content accuracy, customer support for product-related issues, and fulfillment of any promises made to Buyers about the Product.
### 3.3 Relationship to Buyers
When a Buyer purchases a Product through Kelviq Checkout, the Buyer's contractual relationship for the payment transaction is with Kelviq. The Buyer's relationship for the Product and its use is with the Seller, unless the Seller's checkout page or product listing explicitly states otherwise.
## 4. Seller Onboarding and Verification
### 4.1 Account Registration
To sell through Kelviq, you must complete the seller onboarding process, which includes providing accurate business information, verifying your identity, and accepting this Agreement.
### 4.2 Know Your Customer (KYC) and Identity Verification
Kelviq is required to verify the identity of all Sellers before enabling live payment processing. As part of onboarding, you must provide:
* Legal name of the business or individual
* Business registration details (where applicable)
* Business address and country of incorporation or residence
* Identity verification documents as requested by Kelviq or its payment partners
* Tax identification information where required by law
Kelviq reserves the right to request additional information or documentation at any time to maintain compliance with applicable Anti-Money Laundering (AML), Counter-Terrorism Financing (CTF), and sanctions regulations.
### 4.3 Stripe Connected Account
As part of the onboarding process, the Seller must create and maintain a Stripe Connected Account to receive Payouts. By completing this step, the Seller agrees to be bound by the Stripe Connected Account Agreement (available at stripe.com/legal/connect-account) as it may be updated from time to time.
The Seller acknowledges that Kelviq is not a party to the Stripe Connected Account Agreement and that Stripe may independently impose requirements, restrictions, or limitations on the Seller's Connected Account.
### 4.4 Business Review
Before enabling live payment processing, Kelviq will review the Seller's business, products, and intended use of the Platform. Kelviq may approve, conditionally approve, or reject a Seller application at its sole discretion. Approval criteria are described in the Kelviq Approved and Prohibited Business Policy.
Kelviq may re-review a Seller's account at any time and may suspend or terminate access if the Seller no longer meets approval criteria.
### 4.5 Ongoing Compliance
The Seller must promptly notify Kelviq of any material changes to their business, including changes to the types of Products sold, business structure, ownership, country of operation, or any event that could affect the Seller's eligibility under this Agreement or the Approved and Prohibited Business Policy.
## 5. Seller Obligations
### 5.1 Product Responsibility
The Seller is solely responsible for:
* The quality, accuracy, and legality of all Products listed on the Platform
* Ensuring that Products do not infringe on any third-party intellectual property rights, copyrights, trademarks, or patents
* Providing accurate and non-misleading product descriptions, pricing, and marketing materials
* Delivering digital Products to Buyers promptly after purchase (through Kelviq's delivery mechanisms or the Seller's own fulfillment process)
* Providing customer support for product-related issues, including bugs, feature questions, and usage guidance
### 5.2 Legal Compliance
The Seller must comply with all applicable laws and regulations, including but not limited to:
* Consumer protection laws in jurisdictions where Products are sold
* Export control and sanctions regulations (including U.S. OFAC sanctions)
* Data protection and privacy laws applicable to the Seller's business and customers
* Intellectual property laws
* Payment network rules established by Visa, Mastercard, and other applicable card networks
### 5.3 Cooperation with Disputes
When Kelviq receives a Chargeback, dispute, or refund request related to a Seller's Product, the Seller must cooperate promptly by providing requested information, evidence, and documentation within the timeframes specified by Kelviq. Failure to cooperate may result in the dispute being resolved against the Seller.
### 5.4 Accurate Information
The Seller must keep all account information, business details, and product listings current and accurate. The Seller must not provide false, misleading, or incomplete information to Kelviq, Buyers, or any third party in connection with the Platform.
## 6. Fees
### 6.1 Platform Fees
Kelviq charges Platform Fees for use of the Platform services, including payment processing, checkout hosting, and MoR services. The current fee schedule is displayed in the Seller Dashboard and on the Kelviq website ([kelviq.com/pricing](https://kelviq.com/pricing)).
Kelviq may update the fee schedule with at least 30 days' prior written notice to the Seller. Continued use of the Platform after the effective date of a fee change constitutes acceptance of the updated fees.
### 6.2 Payment Processing Fees
Payment processing fees are included in the Platform Fee. The Seller is not charged separate payment processing fees by Kelviq. All fees are displayed in the Seller Dashboard and deducted from the gross transaction amount before the Seller's Net Revenue is calculated.
### 6.3 Fee Deduction
All fees (Platform Fees and payment processing fees) are deducted automatically from the gross transaction amount before Payouts are made to the Seller. The Seller can view a breakdown of all fees in the Seller Dashboard.
### 6.4 Taxes on Fees
Fees quoted by Kelviq are exclusive of any taxes on the fees themselves. If applicable taxes are required to be charged on Kelviq's fees, they will be added to the fee amount.
## 7. Payout Terms
### 7.1 Payout Schedule
Funds from completed transactions are added to the Seller's available balance after processing. Sellers can withdraw their available balance at any time through the Seller Dashboard.
Kelviq may impose a holding period for new Seller accounts during the first 30 days of activity, or for accounts that present elevated risk factors as determined by Kelviq's compliance team.
### 7.2 Payout Method
Payouts are made to the Seller's bank account through the Seller's Stripe Connected Account. The Seller is responsible for maintaining a valid, active bank account and keeping payout details up to date in the Stripe dashboard.
### 7.3 Payout Currency
Payouts are made in the currency associated with the Seller's bank account. Currency conversion, if applicable, is handled by Stripe and subject to Stripe's exchange rates and conversion fees.
### 7.4 Minimum Withdrawal Threshold
Kelviq may set a minimum withdrawal threshold. The current minimum threshold is displayed in the Seller Dashboard.
### 7.5 Payout Holds and Delays
> [!WARNING]
>
> Kelviq may delay, suspend, or withhold Payouts in the following circumstances:
* Pending investigation of suspected fraud, Prohibited Activity, or policy violations
* Open chargebacks or disputes that may result in reversals
* Incomplete or failed KYC verification
* Seller account suspension or termination
* Legal or regulatory requirements, including court orders, subpoenas, or law enforcement requests
* Negative account balance due to refunds, chargebacks, or fee adjustments
## 8. Reserves and Holdbacks
### 8.1 Reserve Rights
Kelviq reserves the right to require a reserve on the Seller's account if Kelviq reasonably determines that the Seller's account presents an elevated financial risk. Risk factors that may trigger a reserve include, but are not limited to:
* High chargeback or dispute rates (typically exceeding 1% of transactions)
* High refund rates (typically exceeding 10% of transactions)
* Sale of products in restricted categories (as defined in the Approved and Prohibited Business Policy)
* Pre-order or delayed delivery products
* Sudden or unexplained spikes in transaction volume
* Negative media coverage or consumer complaints about the Seller's products
### 8.2 Reserve Amounts and Duration
If a reserve is imposed, Kelviq will notify the Seller in writing of the reserve percentage or fixed amount and the expected duration. Reserves may be implemented as a percentage of each transaction (rolling reserve) or as a fixed amount withheld from the Seller's balance. Kelviq will review reserves periodically and release them when the risk conditions that triggered the reserve have been resolved.
### 8.3 Post-Termination Reserve
Upon termination of this Agreement, Kelviq may hold a reserve for up to **180 days** to cover potential chargebacks, refunds, or other liabilities arising from transactions processed during the term of the Agreement.
## 9. Disputes, Chargebacks, and Refunds
### 9.1 Chargeback and Dispute Handling
As the Merchant of Record, Kelviq manages the chargeback and dispute process with payment networks and issuing banks. When a Chargeback is received:
1. Kelviq will notify the Seller and request relevant information and evidence to respond to the dispute
2. The Seller must provide the requested information within the due date mentioned in the notification
3. Kelviq will submit the dispute response to the payment network on behalf of the Seller
4. If the dispute is resolved in favor of the Buyer, the Chargeback amount (plus any applicable fees) will be deducted from the Seller's balance or future Payouts
### 9.2 Chargeback Liability
The Seller is financially responsible for all Chargebacks related to their Products. This includes the original transaction amount and a **\$15 dispute fee** per chargeback. Additional fees imposed by payment networks or processors may also apply.
> [!WARNING]
>
> If the Seller's chargeback rate exceeds the thresholds set by payment networks (typically 0.75%-1.0% of transactions), Kelviq may impose additional restrictions, require a reserve, or terminate this Agreement.
### 9.3 Refund Policy
Kelviq manages refund requests from Buyers. The applicable refund policy is displayed to Buyers at checkout and in the Kelviq customer portal. Refunds may be issued:
* At the Seller's direction through the Seller Dashboard
* By Kelviq in accordance with the refund policy displayed at checkout
* By Kelviq where required by applicable consumer protection law
* By Kelviq to resolve disputes or prevent chargebacks
Refund amounts are deducted from the Seller's balance or future Payouts. Payment processing fees may or may not be refunded depending on the payment method and processor terms.
### 9.4 Excessive Refunds
If the Seller's refund rate exceeds 10% of transactions over any rolling 30-day period, Kelviq may review the Seller's account and take action including requiring product changes, imposing payout holds, or terminating this Agreement.
## 10. Prohibited Activities
The Seller must not engage in any activity that violates applicable law, payment network rules, or the Kelviq Approved and Prohibited Business Policy (available at docs.kelviq.com and incorporated into this Agreement by reference).
> [!WARNING]
>
> Without limiting the foregoing, the Seller must not:
* Sell physical goods, shipping, or logistics services through the Platform
* Sell manual services (coaching, consulting, agency work) where the primary value is manual labor, unless sold as an add-on to a software product
* Operate a marketplace or process payments for unverified third-party sellers through the Platform
* Sell products that are illegal, deceptive, infringing, hateful, or harmful as described in the Approved and Prohibited Business Policy
* Sell regulated financial products, gambling services, adult content, controlled substances, weapons, or pharmaceuticals
* Sell tools designed for spam, hacking, cheating, surveillance, or circumvention of platform rules
* Process transactions that are not genuine sales of Products (including money laundering, structuring, or fraudulent transactions)
* Provide false or misleading information to Kelviq, Buyers, or payment partners
* Attempt to evade Kelviq's review process, compliance monitoring, or enforcement actions
## 11. Data Processing and Privacy
### 11.1 Buyer Data
In connection with transactions processed through the Platform, Kelviq collects and processes Buyer personal data as described in the Kelviq Buyer Privacy Policy (kelviq.com/buyer-privacy). The Seller acknowledges and agrees that Kelviq controls the collection and processing of Buyer payment data and transaction data as the Merchant of Record.
Kelviq may share certain Buyer information with the Seller as needed for product fulfillment and customer support, as described in the Buyer Privacy Policy. The Seller must handle all Buyer data received from Kelviq in compliance with applicable data protection laws.
### 11.2 Seller Data
Kelviq collects and processes Seller personal and business data as described in the Kelviq Privacy Policy (kelviq.com/privacy). Seller data is used for account management, KYC verification, payout processing, compliance, and platform operations.
### 11.3 Stripe Data Processing
The Seller acknowledges that Stripe processes Seller and transaction data as described in Stripe's Privacy Policy (stripe.com/privacy). By creating a Stripe Connected Account, the Seller consents to Stripe's data processing practices.
## 12. Intellectual Property
### 12.1 Seller Content
The Seller retains ownership of all intellectual property in the Products and content uploaded to the Platform. The Seller grants Kelviq a limited, non-exclusive, worldwide license to host, display, process, and distribute the Seller's content solely as necessary to operate the Platform and fulfill transactions.
### 12.2 Kelviq Platform
Kelviq retains all rights in the Platform, including software, design, APIs, documentation, and branding. Nothing in this Agreement grants the Seller any rights in Kelviq's intellectual property beyond the limited right to use the Platform as described in this Agreement.
### 12.3 Trademarks
Neither party may use the other party's trademarks, logos, or brand names without prior written consent, except as reasonably necessary to perform under this Agreement (for example, Kelviq may display the Seller's product name and branding in the checkout experience).
## 13. Representations and Warranties
The Seller represents and warrants that:
* The Seller has the legal authority to enter into this Agreement and perform its obligations
* All information provided to Kelviq during onboarding and thereafter is true, accurate, and complete
* The Seller owns or has valid licenses for all Products sold through the Platform
* The Products do not infringe on any third-party intellectual property rights
* The Seller will comply with all applicable laws, regulations, and payment network rules
* The Seller is not located in, and will not conduct business with individuals or entities in, any country or region subject to U.S. sanctions (as listed in the Approved and Prohibited Business Policy)
* The Seller will not use the Platform for any Prohibited Activity
## 14. Indemnification
### 14.1 Seller Indemnification
The Seller agrees to defend, indemnify, and hold harmless Kelviq, its officers, directors, employees, and agents from and against any claims, damages, losses, liabilities, costs, and expenses (including reasonable legal fees) arising from or related to:
* The Seller's Products, including product defects, misrepresentations, or intellectual property infringement
* The Seller's breach of this Agreement
* The Seller's violation of applicable law or payment network rules
* Disputes between the Seller and Buyers that are not attributable to Kelviq's actions as MoR
* The Seller's handling of Buyer data received from Kelviq
### 14.2 Indemnification Procedure
Kelviq will promptly notify the Seller of any claim subject to indemnification and will provide reasonable cooperation in the defense of the claim. The Seller may not settle any claim without Kelviq's prior written consent if the settlement would impose obligations on Kelviq or admit liability on Kelviq's behalf.
## 15. Limitation of Liability
To the fullest extent permitted by law:
* Kelviq is not liable for indirect, incidental, special, consequential, or punitive damages, including lost profits, lost revenue, lost data, or business interruption, arising from or related to this Agreement or the Seller's use of the Platform.
* Kelviq's total aggregate liability for all claims arising from or related to this Agreement is limited to the total amount of Platform Fees paid by the Seller to Kelviq in the 12 months preceding the event giving rise to the claim.
These limitations apply regardless of the theory of liability (contract, tort, strict liability, or otherwise) and even if Kelviq has been advised of the possibility of such damages.
> [!NOTE]
>
> Some jurisdictions do not allow certain limitations of liability. In those jurisdictions, the above limitations apply to the maximum extent permitted by law.
## 16. Term and Termination
### 16.1 Term
This Agreement is effective from the date the Seller completes onboarding and accepts this Agreement, and continues until terminated by either party.
### 16.2 Termination by Seller
The Seller may terminate this Agreement at any time by providing written notice to Kelviq at [support@kelviq.com](mailto:support@kelviq.com). Termination takes effect upon completion of all pending transactions, resolution of open disputes, and final Payout of any remaining balance (subject to the post-termination reserve described in Section 8.3).
### 16.3 Termination by Kelviq
Kelviq may terminate this Agreement immediately upon written notice if:
* The Seller breaches any material provision of this Agreement
* The Seller engages in Prohibited Activity
* The Seller's chargeback or refund rates exceed acceptable thresholds
* Kelviq is required to do so by law, regulation, or payment network rules
* The Seller's Stripe Connected Account is suspended or terminated by Stripe
* Kelviq ceases to offer the Platform services
Kelviq may also terminate this Agreement for convenience with 30 days' written notice.
### 16.4 Effects of Termination
Upon termination:
* The Seller's access to the Platform will be disabled
* Kelviq will process final Payouts for completed transactions, subject to any reserve hold described in Section 8.3
* The Seller must cease using Kelviq's branding, APIs, and checkout
* Sections that by their nature should survive termination will survive, including Sections 9 (Disputes), 11 (Data), 14 (Indemnification), 15 (Limitation of Liability), and 17 (Governing Law)
## 17. Governing Law and Dispute Resolution
This Agreement is governed by the laws of the State of California, without regard to conflict of laws principles.
Any dispute arising from or related to this Agreement must be brought in the state or federal courts located in San Francisco, California, unless applicable law requires a different venue.
Before initiating any legal proceeding, the parties agree to attempt to resolve disputes through good faith negotiation for a period of at least 30 days.
## 18. General Provisions
### 18.1 Entire Agreement
This Agreement, together with the Kelviq Approved and Prohibited Business Policy, the Kelviq Privacy Policy, and the Kelviq Buyer Terms, constitutes the entire agreement between the parties regarding the subject matter herein. This Agreement supersedes any prior agreements, understandings, or representations related to the same subject matter.
### 18.2 Amendments
Kelviq may update this Agreement from time to time. Material changes will be communicated to the Seller with at least 30 days' notice. Continued use of the Platform after the effective date of a change constitutes acceptance of the updated Agreement.
### 18.3 Assignment
The Seller may not assign or transfer this Agreement without Kelviq's prior written consent. Kelviq may assign this Agreement in connection with a merger, acquisition, or sale of substantially all of its assets.
### 18.4 Severability
If any provision of this Agreement is found to be unenforceable, the remaining provisions continue in full force and effect.
### 18.5 Waiver
Failure by either party to enforce any provision of this Agreement does not constitute a waiver of that provision or the right to enforce it in the future.
### 18.6 Notices
Notices under this Agreement must be sent to the email addresses on file. Kelviq may also provide notices through the Seller Dashboard. Notices are deemed received when delivered to the email address or dashboard.
### 18.7 Independent Contractors
The parties are independent contractors. Nothing in this Agreement creates an employment, partnership, joint venture, or agency relationship between the parties.
### 18.8 Force Majeure
Neither party is liable for delays or failures caused by events beyond reasonable control, including natural disasters, government actions, pandemics, internet outages, or payment network disruptions.
## 19. Contact
Questions about this Agreement should be directed to:
> **Kelviq, Inc.**
>
> 2261 Market Street STE 46163
> San Francisco, CA 94114
>
> Email: [support@kelviq.com](mailto:support@kelviq.com)
# Payment Processing
Source: https://docs.kelviq.com/legal/payment-flow-diagram
Stripe Connect integration and payment flow documentation for Kelviq
## 1. Payment Architecture Overview
Kelviq uses Stripe Connect with **separate charges and transfers** as its payment integration model. Under this model:
* **Kelviq is the Merchant of Record (MoR)** for all transactions. The payment charge is created on Kelviq's platform Stripe account.
* After a successful charge, Kelviq initiates a **separate transfer** to the Seller's Stripe Connected Account for the Seller's share of the revenue (Net Revenue).
* Kelviq deducts Platform Fees and applicable taxes before transferring funds to the Seller.
* The Buyer sees "KELVIQ" (or a Kelviq-branded descriptor) on their bank or card statement.
* Kelviq is responsible for refunds, disputes, and chargebacks as the settlement merchant.
### 1.1 Key Entities
> **Buyer**
>
> Pays for digital products through Kelviq Checkout
> **Kelviq (MoR)**
>
> Platform Stripe account that receives the charge
> **Seller**
>
> Stripe Express Connected Account that receives transfers
> **Stripe**
>
> Payment processor handling charges, transfers, and payouts
## 2. Purchase Payment Flow
The following describes the step-by-step payment flow for a standard purchase through Kelviq Checkout.
**1. Checkout Initiated**
Buyer clicks purchase link and lands on Kelviq-hosted checkout page.
**2. Payment Details Entered**
Buyer enters payment details on Kelviq-hosted checkout (card data collected by Stripe.js).
**3. PaymentIntent Created**
Stripe creates a PaymentIntent on Kelviq's platform account.
**4. Charge Processed**
After successful charge, Kelviq calculates fee split.
**5. Fee Calculation**
Kelviq deducts: Platform Fee + Applicable Taxes = Net Revenue for Seller.
**6. Transfer Initiated**
Kelviq initiates separate Transfer to Seller's Connected Account.
**7. Payout to Seller**
Stripe processes payout to Seller's bank account on schedule.
## 3. Fee Breakdown Example
The following illustrates how a \$100 one-time payment on a domestic card is split, before the Seller reaches \$5,000 in total sales. After \$5,000, the base fee is 3.5% + \$0.40.
| Line Item | Amount |
| - | - |
| Gross Transaction | \$100.00 |
| Kelviq Platform Fee (2.9% + \$0.40) | -\$3.30 |
| **Seller Net Revenue** | **\$96.70** |
**Additional fees may apply:**
* **International cards:** +1.5% (cards issued outside the United States)
* **Subscriptions:** +0.7% (recurring billing transactions)
> [!NOTE]
>
> The Platform Fee includes all payment processing costs. The complete fee schedule is on the [Fees](/getstarted/fees) page.
## 4. Refund Payment Flow
Refunds can be initiated by either the Seller or through Kelviq as the Merchant of Record.
**1. Request**
Buyer requests a refund by contacting the Seller directly (via contact form or email) or by emailing Kelviq at [support@kelviq.com](mailto:support@kelviq.com).
**2. Review & Approval**
The Seller reviews the request and can issue a refund directly through the Seller Dashboard. If the request is made through Kelviq, Kelviq reviews it against the applicable refund policy.
**3. Processing**
Once approved, the refund is processed through Stripe. The refund is issued to the Buyer's original payment method. The refunded amount is deducted from the Seller's balance.
## 5. Chargeback/Dispute Payment Flow
When a Buyer files a chargeback with their bank, the dispute flow is handled by Kelviq as the MoR.
**1. Dispute Filed**
Buyer files chargeback with their bank or card issuer.
**2. Notification Chain**
Bank notifies Stripe, Stripe notifies Kelviq, and Kelviq notifies the Seller.
**3. Evidence Collection**
Seller provides evidence within the due date mentioned in the notification.
**4. Response Submitted**
Kelviq compiles and submits dispute response to Stripe.
**5. Card Network Review**
Card network reviews and decides (typically 60-75 days).
**6. Resolution**
**Won:** Funds returned to Kelviq/Seller. **Lost:** Chargeback amount + \$15 dispute fee deducted from Seller's balance.
## 6. Technical Implementation Details
### 6.1 Stripe Connect Configuration
| Configuration | Value |
| - | - |
| Account type | Stripe Connect with separate charges and transfers |
| Platform account | Kelviq, Inc. (standard Stripe account) |
| Connected accounts | Express accounts for Sellers (Stripe-hosted onboarding) |
| Charge creation | PaymentIntent created on Kelviq's platform account |
| Transfer | Separate Transfer object to Seller's Connected Account after successful charge |
| Statement descriptor | Set on the PaymentIntent, shows "KELVIQ" or a Kelviq-branded descriptor |
| Payout schedule | Manual withdrawals; Sellers can withdraw available balance anytime |
### 6.2 PCI Compliance
Kelviq uses **Stripe.js and Stripe Elements** on the checkout page. Card data is collected directly by Stripe and never passes through or is stored on Kelviq's servers. This keeps Kelviq at the lowest PCI compliance level (**SAQ-A**).
### 6.3 3D Secure and Strong Customer Authentication (SCA)
Kelviq supports **3D Secure (3DS)** authentication through Stripe for transactions where it is required by regulation or recommended for fraud prevention.
For Buyers in the **European Economic Area (EEA)** and the **United Kingdom**, Strong Customer Authentication (SCA) is applied in accordance with the Payment Services Directive 2 (PSD2) requirements. 3DS authentication is triggered automatically by Stripe based on the issuing bank's requirements and Stripe's risk assessment (Stripe Radar).
### 6.4 Tax Handling
Kelviq calculates and collects applicable **sales tax, VAT, or GST** at checkout based on the Buyer's location. Tax amounts are remitted to the appropriate tax authorities by Kelviq as the MoR. Tax is deducted from the gross transaction amount before the Seller's Net Revenue is calculated.
### 6.5 Multi-Currency Support
Kelviq supports checkout in **multiple currencies**. The Buyer pays in the currency displayed at checkout. Currency conversion for Seller payouts is handled by Stripe based on the Seller's Connected Account currency.
## 7. Contact
Questions about Kelviq's payment flow or Stripe integration should be directed to:
> **Kelviq, Inc.**
>
> 2261 Market Street STE 46163
> San Francisco, CA 94114
>
> Email: [support@kelviq.com](mailto:support@kelviq.com)
# Seller Terms
Source: https://docs.kelviq.com/legal/seller-terms
Platform Terms of Service for sellers using Kelviq
> [!NOTE]
>
> **Effective Date:** December 23, 2025
These Terms and Conditions ("Terms") are a contract between you and Kelviq, Inc. ("Kelviq", "we", "us"). By accessing or using our website, app, dashboard, checkout, APIs, or customer portal (together, the "Services"), you agree to these Terms.
## 1. Company Details and Contact
> **Kelviq, Inc.**
>
> 2261 Market Street STE 46163
> San Francisco, CA 94114
>
> Email: [support@kelviq.com](mailto:support@kelviq.com)
## 2. Who These Terms Apply To
These Terms apply to:
* Website visitors
* Users of the Kelviq app and dashboard (including sellers and team members)
* Buyers using checkout and the customer portal
> [!NOTE]
>
> If you are buying through checkout, your purchase is also governed by the Kelviq Buyer Terms. If you are a seller, your use of the platform to sell products is also governed by the Kelviq Seller Master Service Agreement. If there is a conflict between these Terms and the applicable specific agreement, the specific agreement controls.
## 3. Eligibility
You must be 18 or older to use the Services. If you use the Services on behalf of a company, you confirm you have authority to bind that company to these Terms.
## 4. Accounts and Access
* You are responsible for your account and any activity under it.
* Keep your login details and OTP codes secure.
* Tell us if you suspect unauthorized access.
* We can suspend or disable accounts to protect the Services, comply with law, or stop abuse.
## 5. The Services
Kelviq provides tools to help sellers sell digital goods, and to help buyers complete purchases and manage orders.
Kelviq may add, remove, or change features. We will try to avoid breaking changes, but we do not guarantee any specific feature will remain available.
## 6. Merchant of Record and Payments
For all purchases processed through Kelviq checkout, Kelviq acts as the **Merchant of Record**. This means Kelviq is the party shown as the seller on the Buyer's bank or card statement, receipts, invoices, and is responsible for payment processing, refunds, disputes, and applicable tax collection and remittance.
We use Stripe to process payments. We do not store full card numbers on our servers.
The Buyer's bank or card statement will display "KELVIQ" (or "KELVIQ\*" followed by a product identifier) as the merchant name for the transaction.
## 7. Fees
Some parts of the Services may require fees (for example, platform fees or processing fees). Fees, if any, will be shown in the dashboard, checkout flow, an order summary, or an agreement you accept during onboarding.
Unless required by law, fees are non-refundable.
## 8. Seller Responsibilities
If you sell through Kelviq ("Seller"), you agree to the following. For a complete description of the Seller's obligations, refer to the Kelviq Seller Master Service Agreement.
### 8.1 Your Products and Content
* You are responsible for your products, files, license terms, claims, and support promises.
* You will not sell illegal or prohibited items, or content that violates laws or third-party rights.
* You will keep your product description accurate and not misleading.
### 8.2 Customer Support
Unless the checkout page clearly says otherwise, you are responsible for product support, including bugs, feature questions, and usage issues. Kelviq may help route messages, but we are not required to provide product support.
### 8.3 Compliance
You agree to follow all applicable laws and payment network rules, including rules about prohibited products, sanctions, and consumer protection.
### 8.4 Stripe Connected Account
As part of using the platform as a Seller, you must create a Stripe Connected Account and accept the Stripe Connected Account Agreement. You acknowledge that Stripe may independently impose requirements on your Connected Account.
### 8.5 Disputes and Refunds
We may handle payment disputes and chargebacks as part of operating the checkout. We may ask you for information to respond to disputes. You agree to cooperate promptly.
## 9. Acceptable Use
> [!WARNING]
>
> You may not:
* Use the Services for illegal activity
* Attempt fraud, chargeback abuse, or evasion of security checks
* Upload malware or attempt to disrupt the Services
* Scrape, crawl, or reverse engineer the Services except where the law allows it
* Access or download content you did not purchase or do not have rights to
* Impersonate others or misrepresent your identity
We may remove content, block transactions, or suspend accounts to enforce these rules.
## 10. Content, Uploads, and Feedback
You keep ownership of content you upload (product files, text, branding). You grant Kelviq a limited license to host, process, and display that content only to operate the Services.
If you share feedback or suggestions, you allow Kelviq to use them without restriction or payment.
## 11. Intellectual Property
Kelviq owns the Services, including software, design, branding, and related materials. You may not copy, modify, or distribute Kelviq materials unless allowed by law or with our written permission.
## 12. Privacy
Our Privacy Policy explains how we handle personal information. By using the Services, you agree to our Privacy Policy. Stripe processes Seller and transaction data as described in Stripe's Privacy Policy.
## 13. Third Party Services
The Services may rely on third party tools (payments, hosting, email, fraud prevention). Those providers may have their own terms. Kelviq is not responsible for third party services we do not control.
## 14. Suspension and Termination
We may suspend or terminate access to the Services if:
* You violate these Terms
* We believe your activity creates risk, fraud, or harm
* We must do so to comply with law
* Your payments fail or are reversed (for buyer access or seller payouts)
You may stop using the Services at any time.
## 15. Disclaimers
To the fullest extent allowed by law, the Services are provided "as is" and "as available". We do not promise uninterrupted service, error-free operation, or that every payment will succeed.
Sellers are responsible for their products. Kelviq does not promise product quality, fitness, or outcomes from seller products.
> [!NOTE]
>
> Some regions do not allow certain disclaimers, so parts of this section may not apply to you.
## 16. Limitation of Liability
To the fullest extent allowed by law:
* Kelviq is not liable for indirect losses (lost profits, lost revenue, lost data, or business interruption).
* Kelviq's total liability for claims related to the Services is limited to the amount paid to Kelviq for the Services in the 12 months before the event giving rise to the claim.
* For claims tied to a specific buyer purchase, our total liability is limited to the amount paid for that purchase.
> [!NOTE]
>
> Some regions do not allow certain limits, so parts of this section may not apply to you.
## 17. Indemnity
If you are a **Seller**, you agree to defend and indemnify Kelviq from claims arising from your products or content, your promises to buyers, and your violation of law or third-party rights.
If you are a **Buyer**, you agree to indemnify Kelviq for claims arising from your misuse of the Services or violation of these Terms.
## 18. Governing Law and Venue
These Terms are governed by the laws of California, excluding conflict of laws rules. Any dispute must be brought in state or federal courts located in San Francisco, California, unless local law requires another venue.
## 19. Changes to These Terms
We may update these Terms. If changes are material, we will update the effective date and may provide notice through the website, app, dashboard, checkout, or portal. Continued use after the change means you accept the updated Terms.
## 20. Miscellaneous
* If a part of these Terms is unenforceable, the rest still applies.
* You may not transfer your rights under these Terms without our permission. We may assign these Terms as part of a merger, acquisition, or sale of assets.
* These Terms are the full agreement about the Services, except where you have a separate written agreement with Kelviq (such as the Seller Master Service Agreement).
## 21. Contact
Questions about these Terms: [support@kelviq.com](mailto:support@kelviq.com)
# Overview
Source: https://docs.kelviq.com/payouts/overview
Connect your bank account and track cash flow
We use Stripe to ensure you get paid fast and your tax documents are handled automatically.
## Setup
Before you can receive funds, you need to connect a bank account.
**1. Connect account**
Click **Payouts** in the sidebar, then click **Set up payouts**.
**2. Complete onboarding**
You will be redirected to a secure Stripe form. Choose your account type (Individual or Company) and enter your banking details.
## Dashboard
Once set up, the main Payouts view gives you a real-time snapshot of your cash flow.
### Key metrics
* **Available to payout**
The funds that have cleared and are ready to be transferred to your bank.
* **Processing amount**
Revenue that is currently being processed. You can see the estimated date for when these funds will become available.
* **Billing cycle**
Shows your current schedule. If funds are available, you can click **Withdraw funds** to initiate a manual transfer immediately.
### Payout history
Below the metrics, you will see a list of every payout we have sent to your bank.
* Check the status of past transfers.
* See the exact date the funds landed.
* View the destination bank account for each transfer.
## Payout questions
### Do I need a Stripe account?
No. You don't need to sign up for Stripe or have a Stripe account to sell with Kelviq or to get paid.
When you click **Set up payouts**, you verify your identity and add your bank account in a short form run by Stripe Connect. This creates a payout account that only receives your earnings from Kelviq. It's different from a regular Stripe account: you don't sell through it, and Stripe's limits on which countries can open a regular account don't apply.
That's why sellers in countries where Stripe doesn't offer its own accounts, such as India, can still use Kelviq and receive payouts. Check that your country is in the [supported payout countries](/getstarted/review-process#supported-payout-countries) before you go live.
### How long does a payout take?
Sales funds usually become available for payout after seven days. After Kelviq sends the payout, allow another few business days for your bank to post it. Bank holidays, compliance reviews, reserves, and the receiving bank can extend this timing.
### What is the minimum payout?
The minimum payout amount is \$10, or the equivalent amount in the payout currency.
### Are there payout fees?
No. Your full cleared balance is sent to your bank account or eligible debit card. If your bank account uses a different currency, the amount is converted when the payout is sent.
[See the full fee schedule →](/getstarted/fees)
### Do I need a registered company?
No. You can complete payout onboarding as an individual. If you are a sole proprietor and do not have a separate registered company, select **Individual** and provide your own legal and tax details.
### Can I receive a payout in another currency?
Yes. For example, a seller in Canada can receive a payout in USD when the connected bank account accepts USD and that payout currency is available through Stripe Connect. The payout currency follows the connected bank account. If conversion is required, Stripe applies its exchange rate and any conversion fees.
# Payout Settings
Source: https://docs.kelviq.com/payouts/payout-account
Manage bank accounts and transfer schedules
The **Payout Account** tab lets you control how and when you get paid.
## Bank account
View the currently connected bank account. You can also click the link to view your full verification status directly on Stripe.
# Transactions
Source: https://docs.kelviq.com/payouts/transactions
Audit individual payments, fees, and net earnings
The **Transactions** tab shows successful payments, refunds, and failed payments. Use it to see what the customer paid, the fees and tax deducted, and the amount added to your balance.
## Filtering
You can filter the list by status to find specific issues.
* **Success:** Completed payments.
* **Pending:** Payments that have not finished processing.
* **Refunded:** Money returned to customers.
* **Failed:** Declined cards or failed transfers.
The search field also matches payment method types. Search for `upi`, `card`, `link`, `amazon_pay`, or `sepa_debit` to see payments made through that method.
## Transaction details
Click a transaction row to open its details.
* **Gross total:** The full amount charged to the customer, including tax.
* **Fee:** The combined transaction fees deducted by Kelviq.
* **Tax:** Tax collected for the transaction and excluded from your net earnings.
* **Net earnings:** The amount added to your Kelviq balance after transaction fees and tax. There's no payout fee, so nothing more is deducted when the balance is sent to your bank.
* **Payment details:** The card or method used.
For a successful transaction:
```text theme={null}
Net = Gross - Fee - Tax
```
## How the Fee column is calculated
The **Fee** column shows one combined amount. Depending on the transaction, that amount can contain up to three components:
| Component | Rate | When it applies |
| - | - | - |
| Base fee before \$5,000 in total volume | 2.9% + \$0.40 | Transactions processed before your organization reaches \$5,000 in cumulative sales |
| Base fee after \$5,000 in total volume | 3.5% + \$0.40 | Subsequent transactions after your organization reaches \$5,000 in cumulative sales |
| Recurring billing | +0.7% | Subscription payments and renewals |
| International card | +1.5% | Cards issued outside the United States |
Recurring and international-card fees are added to the base rate when they apply. For example, an international subscription payment processed after the \$5,000 threshold is charged 5.7% + \$0.40: 3.5% base, 0.7% recurring, and 1.5% international.
### Example from the transaction list
For a \$57.60 domestic, one-time payment processed after the \$5,000 threshold:
```text theme={null}
Fee = ($57.60 × 3.5%) + $0.40
= $2.42 after rounding
Net = $57.60 gross - $2.42 fee - $9.60 tax
= $45.58
```
The percentage is calculated from the gross customer charge. The fixed \$0.40 is added once. Kelviq rounds the final fee to the smallest unit of the transaction currency.
[See the complete fee table and more examples →](/getstarted/fees)
> [!NOTE]
>
> There's no payout fee. See [Payout fees](/getstarted/fees#payout-fees).
# Create a feature in Kelviq
Source: https://docs.kelviq.com/product-catalog/create-a-feature
Create Boolean, Meter, or Customizable features in the Kelviq dashboard or with the API, then add them to a plan as entitlements.
A feature is something your product can enable, limit, or measure for a customer. Examples include analytics access, team size, API calls, storage, and AI credits.
Create the feature once, then reuse it across plans. Creating a feature does not grant it to anyone. You must add it to a plan as an entitlement before customers receive access.
## Choose a feature type
| Dashboard option | API value | Use it for |
| - | - | - |
| Boolean | `BOOLEAN` | On-or-off access, such as analytics, SSO, or priority support |
| Meter | `METER` | A quantity that is purchased or consumed, such as seats, API calls, storage, or credits |
| Customizable | `CUSTOMIZABLE` | A plan-specific numeric limit or setting, such as maximum projects or upload size |
> [!TIP]
>
> Use an identifier that is short, stable, and easy to use in code, such as `api-calls` or `advanced-analytics`. You can rename a feature later, but its identifier and type cannot be changed after creation.
## Method 1: Create a feature in the dashboard
1. Open **Product catalog → Features** in the [Kelviq dashboard](https://app.kelviq.com/features).
2. Click **Create feature**.
3. Enter a **Feature name**. This is the readable name shown in the dashboard.
4. Enter an **Identifier**. Your application uses this value when checking access or reporting usage.
5. Add a **Description** if your team needs more context about what the feature controls.
6. Choose the **Feature type**:
* **Boolean** for on-or-off access.
* **Meter** for purchased or consumed quantities.
* **Customizable** for a numeric limit or setting.
7. For a Meter feature, enter the singular and plural units. For example, use `call` and `calls`, or `seat` and `seats`.
8. Click **Create**.
Turn on **Create more** before saving if you want the form to remain open for another feature.
> [!NOTE]
>
> The dashboard creates Meter features for pre-aggregated usage. Your application reports the quantity with the usage reporting API or an SDK. A purchased quantity such as seats can also come from checkout or a subscription update.
## Method 2: Create a feature with the API
Use the Catalog Features API when features are managed from an internal tool, provisioning script, or automated setup flow. Send the Server API Key from a trusted backend.
```bash theme={null}
curl --request POST \
--url https://api.kelviq.com/api/v1/catalog/features/ \
--header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "API Calls",
"identifier": "api-calls",
"description": "Number of API calls available in a billing period.",
"featureType": "METER",
"featureDetails": {
"featureSubType": "PRE_AGGREGATED_USAGE",
"units": {
"singular": "call",
"plural": "calls"
}
}
}'
```
Use `https://sandboxapi.kelviq.com/api/v1/catalog/features/` with a sandbox Server API Key when testing. Sandbox and production features are separate.
### Request fields
| Field | Required | Description |
| - | - | - |
| `name` | Yes | Readable feature name |
| `featureType` | Yes | `BOOLEAN`, `METER`, or `CUSTOMIZABLE` |
| `identifier` | No | Stable code-facing identifier; Kelviq generates one from the name when omitted |
| `description` | No | Internal explanation of what the feature controls |
| `featureDetails` | For Meter setup | Meter subtype and units |
| `meter` | For raw-event meters | Aggregation and filter configuration |
| `metadata` | No | Additional key-value data for your own workflow |
For a Boolean or Customizable feature, the request can be shorter:
```json theme={null}
{
"name": "Advanced Analytics",
"identifier": "advanced-analytics",
"featureType": "BOOLEAN"
}
```
The API returns `201 Created` with the new feature, including its Kelviq UUID. See the [Create a feature API reference](/api-reference/features/create-a-feature) for the complete request and response schema.
## Add the feature to a plan
The feature remains independent until you attach it to a plan:
1. Open **Product catalog → Products** and select a product.
2. Open the plan you want to configure.
3. Go to **Features & limits** and choose **Manage features & limits**.
4. Search for the feature and add it to the plan.
5. Configure the entitlement value:
* Enable or disable a Boolean feature.
* Enter the allowed value for a Customizable feature.
* Set the limit, reset cadence, hard-limit behavior, rollover, or alerts for a Meter feature.
6. Save the plan. Publish the draft when it is ready for customers.
Read [Features & limits](/product-catalog/entitlements) to check access from your application, [Usage-based pricing](/product-catalog/usage-based-billing) to price metered consumption, or [Seat-based pricing](/product-catalog/seat-based-pricing) to sell purchased quantities.
## Common problems
| Problem | What to check |
| - | - |
| The feature does not appear for customers | Confirm that it was added to the correct plan and that the plan version was published |
| Usage reports return a feature error | Send the exact feature identifier, not its display name |
| A Meter feature cannot be created | Enter both the singular and plural unit names |
| The feature exists in Sandbox but not Production | Create it separately in the production environment |
| The identifier or type is wrong | Create a new feature; these fields cannot be changed after creation |
# Digital Downloads
Source: https://docs.kelviq.com/product-catalog/digital-downloads
Enable customers to download digital files after purchase
Digital Downloads allow you to attach downloadable files to your plans. Customers who purchase your plan can access these files after completing their purchase.
## Overview
Use Digital Downloads to deliver:
* **Course content** – PDFs, videos, or supplementary materials
* **E-books** – Digital books in PDF, EPUB, or other formats
* **Software** – Installers, license files, or application packages
* **Templates** – Design files, spreadsheets, or document templates
* **Any other digital content** your customers need
## Accessing Digital Downloads
1. Navigate to **Products** in the sidebar
2. Select the product containing your plan
3. Click on the plan you want to edit
4. Scroll down to the **Digital downloads** section
5. Click the expand arrow to open the section
## Uploading Files
### How to Upload
1. Open the **Digital downloads** section
2. Click anywhere in the upload area, or drag and drop files directly
3. Select one or more files from your computer
4. Files will begin uploading automatically
5. Once complete, files appear in the **Uploads** list
### Upload Progress
While uploading, you'll see:
* File name and size
* Progress bar showing upload percentage
* Status indicator (uploading, complete, or error)
### File Size Limits
* **Maximum file size**: 5 GB per file
* **Multiple files**: You can upload multiple files at once
### Supported File Types
All file types are supported, including:
* Documents: PDF, DOCX, TXT, etc.
* Images: PNG, JPG, GIF, SVG, etc.
* Videos: MP4, MOV, AVI, etc.
* Audio: MP3, WAV, FLAC, etc.
* Archives: ZIP, RAR, 7Z, etc.
* Software: EXE, DMG, APP, etc.
* Any other file format
## Managing Files
Each uploaded file has a toggle switch and a menu button (**⋯**) with additional options.
### Enable/Disable Files
You can temporarily hide files from customers without deleting them:
1. Find the file in the uploads list
2. Click the toggle switch next to the file
3. **Enabled** (toggle on): Customers can download this file
4. **Disabled** (toggle off): File is hidden from customers
This is useful when you need to temporarily remove access to a file or prepare files before making them available.
### File Actions Menu
Click the menu button (**⋯**) next to any file to access additional options:
#### Download
Use the **Download** option to:
* Verify that the file uploaded correctly
* Check file contents before enabling for customers
* Save a local backup of uploaded files
To download a file:
1. Click the **⋯** menu button next to the file
2. Select **Download**
3. The file will download to your computer
#### Delete
To permanently remove a file:
1. Click the **⋯** menu button next to the file
2. Select **Delete**
3. The file will be permanently removed
> **Note**: Deleted files cannot be recovered. Make sure you have a backup before deleting.
## Customer Experience
After a successful purchase, customers can:
1. Access the order confirmation page
2. View all downloadable files associated with their purchased plan
3. Click to download each file directly
Files remain accessible to customers as long as their subscription or purchase is active.
# Discounts
Source: https://docs.kelviq.com/product-catalog/discounts
Create coupons and promotional codes
You can manage all your coupons from the **Product Catalog**.
Navigate to **Product Catalog > Discounts** to see a list of every active and expired code.
You can create two types of discounts:
* **Percentage** — Reduces an eligible price by a percentage, such as 20%.
* **Fixed amount** — Subtracts a specific amount in a selected currency, such as USD 10 or INR 500.
For a fixed-amount discount, select the currency next to the amount. Kelviq places the currency from your organization profile first in the list, but you should still review the selection before creating the discount.
## Create a discount
**1. Start creation**
Click **+ Create discount** in the top right corner.
**2. Define value**
Choose the discount type (Percentage or Fixed amount) and enter the value.
* **Name:** The internal name for your reference.
* **Discount code:** The text the customer enters at checkout. You can type your own or click the **refresh icon** to auto-generate a secure random code.
**3. Configure rules**
Set the duration, limits, and product scope (detailed below).
**4. Create**
Click **Create discount** to make the code live immediately.
## Configuration options
You can control exactly how and when a discount applies.
### Duration
Recurring discount settings are enabled by default. Choose how long the discount should apply:
* Enter a number of billing cycles for a limited recurring discount.
* Select **Discount applies forever** to apply it to every eligible recurring invoice.
* Turn off **Recurring discount** when the code should apply only to the initial purchase.
### Usage & expiry
Control the scarcity of the coupon.
* **Redemption limit:** Set a total number of times this code can be used (e.g. "First 100 users").
* **Expiry date:** Set a hard deadline when the code stops working.
### Product restrictions
By default, a discount applies to the entire catalog. To restrict it:
1. Enable **Limit discount to selected products**.
2. Select a product in every restriction row you add.
3. Optionally select a specific plan price. Choose **Applies to all plans** to include every price under that product.
Kelviq will not create the discount while a restriction row has no product selected.
For fixed-amount discounts, the discount currency must match the currency of the selected price. Kelviq shows a validation error when the currencies do not match.
## Apply a discount at checkout
Customers can enter a code themselves, or you can pre-apply one through the Checkout API or a static checkout link. See [Apply a discount code at checkout](/checkout/apply-a-discount-code) for working examples and field names.
## Management
The main discounts tab shows the status of every code you have created.
* **Active:** The code is live and redeemable.
* **Expired:** The code has passed its end date or hit its usage limit.
# Features & limits (entitlements)
Source: https://docs.kelviq.com/product-catalog/entitlements
Entitlements decide which features and limits each customer gets
Check features, not plans. Your code asks whether a customer has a feature, and Kelviq answers from their plan. You can change plans, prices, and custom deals without changing code. In the API and SDKs, a feature on a plan is called an entitlement.
> [!NOTE]
>
> For SDK installation and API reference, see:
>
> * [Node SDK Documentation](https://docs.kelviq.com/backend-integration/node-sdk)
> * [Entitlements API Reference](https://docs.kelviq.com/api-reference/entitlements/retrieve-customer-entitlements)
***
## Why Entitlements?
### The Problem with Plan-Based Access
Traditional SaaS applications check access like this:
```javascript theme={null}
// ❌ The old way - hardcoded, brittle, requires code changes
if (user.plan === 'pro' || user.plan === 'enterprise') {
showAdvancedAnalytics();
}
if (user.plan === 'enterprise') {
enableSSO();
}
```
This approach has serious limitations:
* **Code changes required** for any pricing restructure
* **Deployment needed** to move a feature between plans
* **Engineering bottleneck** for every pricing experiment
* **Stale cache issues** when plans change
* **Custom deals are painful** requiring one-off code
### The Entitlements Approach
With Kelviq, you check features directly:
```javascript theme={null}
// ✅ The Kelviq way - flexible, decoupled, no code changes needed
const hasAnalytics = await client.entitlements.hasAccess({
customerId: "cust_123",
featureId: "advanced-analytics"
});
if (hasAnalytics) {
showAdvancedAnalytics();
}
```
Now you can:
* Move features between plans without code changes
* Create custom enterprise deals in minutes
* A/B test pricing without deployments
* Let Sales and Product iterate independently
***
## How It Works
### The Flow
1. Setup plans and features on Kelviq Dashboard
2. When a customer completes checkout, their entitlements are automatically assigned.
3. Your app checks access via SDK
4. Customer gets immediate access
### Access right after checkout
When a customer completes checkout:
1. Payment is processed
2. Entitlements are assigned **automatically**
3. Your app checks access via SDK
4. Customer gets immediate access
Your app checks access with Kelviq, so you don't have to copy subscription state into your own database. If you want to react to changes in your own systems, use [webhooks](/guides/webhooks).
***
## When the Entitlement API is unavailable
Kelviq serves entitlement checks through its edge API. The service targets P95 response times below 100 ms and an uptime SLA above 99.99%, but your access-control path should still account for a temporary network or API failure.
### Node and Python SDK fallback
The current Node and Python SDKs cache entitlement responses by default. Each process keeps a fresh in-memory entry for 60 seconds. If the edge API is unreachable or returns a server error, the SDK can return the last known entitlement state instead of failing the access check.
The in-memory cache is local to one process and is lost when that process restarts. For multiple application instances, workers, or containers, configure the optional Redis store. It shares the cache across instances and keeps the fallback state available through application restarts.
Usage and event reports that fail because of a temporary network problem are queued. The SDK retries them on the next report call, or you can flush the queue explicitly. An in-memory queue is suitable for one process; use Redis when the queue must be shared and durable.
> [!WARNING]
>
> The SDK cannot return a last known value for a customer or feature that has never been fetched. Decide whether your application should deny access, allow limited access, or show a temporary error when no cached state exists.
See the [Node SDK caching configuration](/backend-integration/node-sdk#caching-and-offline-resilience) or [Python SDK caching configuration](/backend-integration/python-sdk#caching-and-offline-resilience) for setup examples.
### Calling the API directly
If you call the Entitlement API without an SDK, keep your own last-known response in an in-memory or persistent cache. Store when the value was fetched, set a maximum fallback age that matches the risk of the feature, and refresh the record after the API recovers.
Use a short fallback window for high-risk actions such as exporting sensitive data or using an expensive Meter feature. A longer window may be reasonable for low-risk interface features. Do not silently grant access when there is no previous entitlement state.
If your architecture already maintains subscription state through webhooks, you can continue using that model. Process webhook events idempotently and reconcile the local record against the Entitlement API after an outage.
***
## Feature Types
Kelviq supports three types of features to cover all access control scenarios.
### Boolean Features
Simple on/off access control.
**Use for:**
* Feature flags (SSO, API access, white-labeling)
* Premium features (advanced analytics, custom branding)
* Access gates (admin panel, beta features)
**Example configuration:**
| Feature | Starter | Pro | Enterprise |
| - | - | - | - |
| Basic Dashboard | ✓ | ✓ | ✓ |
| Advanced Analytics | ✗ | ✓ | ✓ |
| SSO | ✗ | ✗ | ✓ |
| White Label | ✗ | ✗ | ✓ |
### Meter Features
Usage-based features with limits and tracking.
.png?fit=max\&auto=format\&n=dIayyoP2MxhiM3vQ\&q=85\&s=79944e812b9e3720e950502494285370)
**Use for:**
* API calls, requests, or operations
* Storage (GB, files, records)
* Team members or seats
* Messages, emails, or notifications
* AI tokens or credits
**Configuration options:**
| Option | Description |
| - | - |
| **Limit** | Maximum usage allowed (or unlimited) |
| **Reset Period** | When usage resets (monthly, weekly, daily, never) |
| **Hard Limit** | Block access when limit reached |
| **Soft Limit** | Allow overages but notify/warn |
| **Rollover** | Carry unused quota to next period |
**Example configuration:**
| Feature | Starter | Pro | Enterprise |
| - | - | - | - |
| API Calls | 1,000/mo | 100,000/mo | Unlimited |
| Storage | 5 GB | 100 GB | 1 TB |
| Team Members | 3 | 25 | Unlimited |
### Customizable Features
Dynamic values that aren't simple on/off or numeric limits.
**Use for:**
* Configuration values
* Tier-specific settings
* Dynamic feature behavior
***
## Soft Limits vs. Hard Limits
Choose the right enforcement strategy for each feature. [How usage limits work](/product-catalog/usage-limits) walks through resets, overage, and what happens at the limit.
### Hard Limits
Block access completely when the limit is reached.
**Best for:**
* Cost-sensitive features (AI tokens, bandwidth)
* Preventing abuse
* Strict contractual limits
### Soft Limits
Allow continued access but notify the user.
**Best for:**
* Driving upgrades without blocking users
* Features where occasional overages are acceptable
* Better user experience during high-usage periods
***
## Checkout Integration
When a customer goes through checkout, entitlements are automatically assigned. The key is passing the customer ID.
### Passing Customer ID
When creating a checkout session, include the customer identifier:
```javascript theme={null}
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://yourapp.com/checkout/success",
customerId: "cust_789", // Your customer ID - recommended
});
```
> [!TIP]
>
> Always pass a `customerId` when creating checkout sessions. If you don't, a new customer will be created automatically, which may lead to duplicate customer records.
For complete checkout API options, see the [Node SDK Documentation](https://docs.kelviq.com/backend-integration/node-sdk).
### New vs. Existing Customers
| Scenario | What Happens |
| - | - |
| **New customer ID** | Customer created automatically, entitlements assigned |
| **Existing customer** | Entitlements updated based on new purchase |
| **Upgrade** | New plan entitlements replace old ones |
| **Downgrade** | New plan entitlements replace old ones immediately |
### Automatic Assignment
After successful payment:
1. Customer record is created/updated
2. Plan entitlements are assigned instantly
3. Customer can access features immediately
***
## SDK Integration
### Quick Start
Install the SDK and start checking entitlements in minutes.
```bash npm theme={null}
npm install @kelviq/node-sdk
```
```bash yarn theme={null}
yarn add @kelviq/node-sdk
```
```javascript theme={null}
import { Kelviq } from '@kelviq/node-sdk';
const client = new Kelviq({
accessToken: process.env.KELVIQ_SERVER_API_KEY,
environment: process.env.KELVIQ_ENV, // 'sandbox' or 'production'
});
```
> [!NOTE]
>
> Get your API key from **Settings → [API keys](https://app.kelviq.com/settings/api-keys)** in the Kelviq dashboard.
### Checking Feature Access
```javascript theme={null}
// Check boolean feature access
const hasAccess = await client.entitlements.hasAccess({
customerId: "cust_123",
featureId: "advanced-analytics"
});
if (hasAccess) {
showAdvancedAnalytics();
} else {
showUpgradePrompt();
}
```
### Reporting Usage
For meter features, report usage after each consumption:
```javascript theme={null}
import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';
// Increment usage by a value (DELTA)
await client.reporting.reportUsage({
value: 1,
customerId: "cust_123",
featureId: "api-calls",
behaviour: BEHAVIOUR_CHOICES.DELTA // Adds to current usage
});
// Or set absolute value (SET)
await client.reporting.reportUsage({
value: 150,
customerId: "cust_123",
featureId: "seats",
behaviour: BEHAVIOUR_CHOICES.SET // Replaces current usage
});
```
> [!NOTE]
>
> For complete SDK reference including all methods and parameters, see the [Node SDK Documentation](https://docs.kelviq.com/backend-integration/node-sdk).
> [!WARNING]
>
> The sandbox environment is completely separate from production. Use different API keys and note that sandbox data won't appear in production.
***
## Manage feature definitions
Open **Product Catalog → Features** to create and manage reusable feature definitions. See [Create a feature in Kelviq](/product-catalog/create-a-feature) for the complete dashboard and API workflows.
* Use the row action menu to edit a feature name.
* Metered values, percentages, and rollover limits use numeric inputs.
* When configuring a metered entitlement, set the usage reset and hard-limit behavior first, then configure credit rollover and usage alerts.
When adding features to a plan from **Manage features & limits**, search for a feature and click **Add**. Kelviq clears the search after the feature is added so you can search for the next feature immediately.
***
## Managing Customer Entitlements
### Viewing Customer Entitlements
In the Kelviq dashboard:
1. Navigate to **Customers**
2. Select a customer
3. View their **Features** section
You'll see:
* All entitled features
* Current usage vs. limits
* Reset dates for meters
* Whether values are overridden
### Overriding Entitlements
Sometimes you need to give a specific customer different access than their plan provides.
**Common scenarios:**
* Sales gave a prospect extra API calls for a POC
* Customer needs temporary limit increase
* VIP customer gets special access
* Compensating for a service issue
**To override:**
1. Go to the customer's detail page
2. Find the feature in the Features section
3. Click the menu (⋯) → **Override usage**
4. Set the new value
5. Save
Overrides are:
* Per-customer (don't affect the plan)
* Marked with an override indicator
* Can be reverted anytime
### Resetting Usage
For meter features, you can reset a customer's usage:
1. Go to the customer's detail page
2. Find the Meter feature
3. Click the menu (⋯) → **Reset usage**
This sets their current usage back to 0, giving them their full quota again.
***
## Plan Inheritance
Create plan hierarchies to reduce duplication and maintain consistency.
### How It Works
```
Enterprise Plan
└── inherits from → Pro Plan
└── inherits from → Starter Plan
```
When you set up inheritance:
* Child plan automatically gets parent's features
* You can override specific values in the child
* Changes to parent propagate to children (unless overridden)
### Override Indicators
| Icon | Meaning |
| - | - |
| 🔗 Inherited | Value comes from parent plan, stays in sync |
| ⚡ Overridden | Value was customized, no longer syncs with parent |
### Use Cases
**Tiered plans:**
* Starter: 1,000 API calls
* Pro: inherits Starter + overrides API calls to 100,000 + adds analytics
* Enterprise: inherits Pro + overrides to unlimited + adds SSO
**Regional plans:**
* US Pro: standard features
* EU Pro: inherits US Pro + adds GDPR compliance features
***
## Subscription Lifecycle
### What Happens During...
#### Successful Purchase
* Entitlements assigned immediately
* Customer can access features right away
#### Upgrade
* New plan entitlements replace old ones
* Happens immediately
* Existing usage counters are retained and evaluated against the new limits
#### Downgrade
* New plan entitlements replace old ones immediately
* Existing usage counters are retained
* A customer can become over limit when the new limit is below current usage
#### Cancellation
* Immediate cancellation revokes plan access immediately
* Period-end cancellation keeps entitlements active until the subscription expires
#### Failed Payment
* A failed card renewal moves the subscription to `past_due`
* Kelviq retries card payments for up to 14 days before cancellation
* Failed non-card renewals are not retried and the subscription is cancelled
#### Refund
* Cancelling mid-period does not automatically create a refund
* The merchant decides whether to issue a full, partial, or no refund
> [!NOTE]
>
> Manage subscriptions programmatically using the [Subscriptions API](https://docs.kelviq.com/backend-integration/node-sdk#subscriptions).
***
# Free plans and trials
Source: https://docs.kelviq.com/product-catalog/free-and-trials
Set up lead magnets and trial periods
You do not always need to charge upfront. Kelviq lets you offer completely free plans or time restricted trials to help acquire users.
## Free plans
Use a free plan to offer a permanent zero cost tier. This is perfect for open source products, lead magnets, or a basic hobby tier where you want to gather signups without requiring a credit card.
1. Open your draft plan
2. Toggle the switch in the top right from Paid to Free
3. Save your changes
Users who select this plan bypass the payment step entirely. They still get access to the customer portal and any deliverables or entitlements attached to the plan.
### Putting new signups on a free plan
Entitlement checks return `false` for a customer Kelviq has never seen, so a free plan only takes effect once the customer has a subscription to it. To enrol someone at signup rather than sending them through checkout:
1. Create the customer **with an email address** — `customers.create` in the SDK, or `POST /customers/`.
2. Create the subscription — `POST /subscriptions/create/` with the plan's identifier and `chargePeriod: "ONE_TIME"`.
Keep that order, and enrol at signup, before the customer reaches checkout. Creating a subscription for a customer Kelviq has not seen fails with `Subscription requires a customer with a valid email address` — and the failed attempt still registers the customer, without an email. Creating a checkout session with a `customerId` registers the customer the same way. From then on `POST /customers/` answers `Customer already exists`, and the portal refuses that customer too. Recover by patching the email onto the existing record with `PATCH /customers/{customerId}/`, after which the subscription call succeeds. Treat `Customer already exists` as a signal to patch rather than an error to surface.
Enrolling this way also records a \$0 order for the plan.
Check for an existing subscription first, with `customer_id` on `GET /subscriptions/`. Creating a second subscription for the same customer is allowed: the new one becomes `active` and the previous one becomes `superseded`. Nothing breaks, but enrolling on every visit churns through subscription records for no reason.
## Free trials
Free trials let customers test a paid plan for a specific number of days before their card is charged.
> [!NOTE]
>
> Trials are available only when the plan has at least one recurring billing cycle. A one-time-only plan does not show trial settings and will not display a trial at checkout.
1. Open a paid plan draft.
2. Enable at least one recurring billing cycle, such as **28 days**, **Monthly**, or **Yearly**.
3. Enable **Free trial**.
4. Enter the number of days the trial should last.
If you later disable the final recurring billing cycle and leave only one-time pricing, Kelviq removes the trial from the one-time offer.
When a customer signs up they must enter a valid payment method. We authorize the card but do not charge it. When the trial period ends Kelviq automatically charges the card and begins the regular billing cycle.
If the user cancels before the trial ends they are not charged.
# License Key Management
Source: https://docs.kelviq.com/product-catalog/license-keys
Generate and manage license keys for your products
License keys allow you to generate unique activation keys for each customer purchase. This guide covers how to enable and configure licenses on your plans, manage them from orders, and how your customers can activate and validate licenses using the API.
***
## 1. Enabling Licenses on a Plan
License keys are configured at the **plan level**. When enabled, every order placed for that plan will automatically generate a unique license key for the customer.
### How to Enable Licenses
1. Go to **Product catalog → Products** → Select your product → Select the plan you want to configure
2. Scroll down to the **License keys** section
3. Toggle the switch to **enable** license keys
### Configuration Options
Once enabled, you can configure the following settings:
#### Activation Limit
Control how many times a single license key can be activated across different devices.
| Setting | Description |
| - | - |
| **Enabled** | Limit activations to a specific number (e.g., 5 devices) |
| **Disabled** | Unlimited activations allowed |
> **Use case**: Set a limit of 3 if you want customers to use the license on up to 3 computers.
#### License Expiry
Define how long the license key remains valid after purchase.
| Setting | Description |
| - | - |
| **Enabled** | License expires after a specified duration |
| **Disabled** | License never expires |
When expiry is enabled, you can set:
* **Duration value**: A number (e.g., 1, 6, 12)
* **Duration unit**: Days, Months, or Years
> **Example**: Setting duration to `12 Months` means the license expires 12 months after the purchase date.
### Save Your Configuration
After configuring the settings, click **Save Changes**. All future orders for this plan will use these license settings.
***
## 2. Managing licenses from an order
Once a customer places an order for a plan with licenses enabled, you can manage their license from the order. Go to **Sales → Orders**, click the customer, and open the **License** tab.
### Viewing License Information
The **License** tab displays:
* **License Key**: The unique key assigned to this order
* **Expiry Date**: When the license expires (or "Never expires")
* **Activation Status**: Active count vs. limit (e.g., "2/5 activations" or "3/Unlimited")
* **License Status**: Active or Deactivated
### Available Actions
Click the **⋯** menu button on the license card to access these options:
#### 🔄 Regenerate Key
Creates a brand new license key and invalidates the old one.
* The old key will immediately stop working
* Customer must use the new key for future activations
* Existing activations will stop working
> ⚠️ **Warning**: This action cannot be undone. Use when a key has been compromised or shared inappropriately.
#### ✏️ Edit Activation Limit
Modify how many devices can use this specific license.
* Toggle activation limit on/off
* Set a specific number (1-100 activations)
* Changes apply immediately
> **Use case**: Upgrade a customer from 3 seats to 10 seats without issuing a new license.
#### 📅 Manage Expiry
Update the license expiration date.
* Toggle expiry on/off
* Set a specific expiration date using the calendar picker
* Extend or shorten the validity period
> **Use case**: Extend a license by 3 months as a courtesy for a loyal customer.
#### ⛔ Deactivate License
Permanently disable the entire license.
* All existing activations will stop working
* Customers will no longer be able to activate or validate the key
* The license key becomes invalid
> ⚠️ **Warning**: This action cannot be undone. Use for refunds or policy violations.
### Viewing Active Activations
Click on the license card to view the **License Details** page, which shows:
* All instances where the license is currently activated
* Instance name or ID
* Last seen timestamp (when the license was last validated)
* Activation metadata (device info, if provided)
#### Revoking Individual Activations
For each active instance, you can click **Revoke** to:
* Remove that specific instance's access
* Free up an activation slot
* The license remains valid for other instances
> **Use case**: Customer got a new computer and wants to transfer their license. Revoke the old instance to free up a slot.
***
## 3. License API for Developers
Your customers (or their software) can interact with licenses using these API endpoints. Use these to integrate license checking into your application.
### Authentication
The Activate, Validate, and Deactivate License APIs accept either a **Client API Key** or a **Server API Key** as a Bearer token:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
Choose the key based on where the request originates:
| Request origin | API key | Guidance |
| - | - | - |
| Browser, desktop app, mobile app, CLI, or plugin | Client API Key | Safe to include in distributed client software. The customer still supplies the license key. |
| Your backend or another trusted server | Server API Key | Keep it secret and load it from your server environment. |
Both key types can call `POST /license/activate/`, `POST /license/validate/`, and `POST /license/deactivate/`. Use a key from the same environment as the license: a sandbox key with a sandbox license, or a production key with a production license.
> [!WARNING]
>
> Never expose a Server API Key in frontend code or software distributed to customers. Use a Client API Key for those integrations.
### Reading a customer's key from your server
A customer's keys come back with their purchase records, authenticated with your server API key. Orders, subscriptions and invoices all carry a `license` array, and each entry holds `licenseKey` alongside `activationUsage`, `activationLimit` and `expiresOn`.
Which record to read depends on how the plan is sold:
* **One-time purchases** produce an order, not a subscription. Read `GET /orders/`, where each order's `billingType` is `ONE_TIME`. Orders have no customer filter — pass the customer's id or email as `search` to narrow the list to them.
* **Recurring plans** produce a subscription. Read `GET /subscriptions/?customer_id=`.
This matters for how much you ask of the customer. A signed-in web app already knows who the customer is, so it can read the key server-side and activate on their behalf — there is no need to make them find an email and paste a key back into a session you control. Ask for the key only where the software has no way to look it up itself: a desktop app, CLI, plugin, or anything running off your server, which cannot hold a server API key.
### 3.1 Activate a License
Activates a license key on a specific device/instance.
**Endpoint**: `POST /license/activate/`
**Authentication**: Client API Key or Server API Key
**When to use**:
* When the user enters their license key for the first time
* When your application is installed on a new device
**What it does**:
* Validates the license key exists and is valid
* Checks if activation limit has been reached
* Creates a new activation instance
* Returns activation details including instance ID
**Key behaviors**:
* Fails if the license is expired
* Fails if the license is deactivated
* Fails if activation limit is reached
* Succeeds and increments the activation count
📖 **Full documentation**: [Activate License API](https://docs.kelviq.com/api-reference/license/activate-license)
***
### 3.2 Validate a License
Checks if a license is valid and currently active.
**Endpoint**: `POST /license/validate/`
**Authentication**: Client API Key or Server API Key
**When to use**:
* On application startup to verify the license
* Periodically during runtime
* Before granting access to licensed features
* When checking license status without activating
**What it does**:
* Confirms the license key exists
* Checks if the license is active (not deactivated)
* Verifies the license hasn't expired
* Returns current license status and metadata
**Response includes**:
* License validity status
* Expiration date
* Activation count and limit
* License metadata
📖 **Full documentation**: [Validate License API](https://docs.kelviq.com/api-reference/license/validate-license)
***
### 3.3 Deactivate a License
Removes an activation from a specific device/instance.
**Endpoint**: `POST /license/deactivate/`
**Authentication**: Client API Key or Server API Key
**When to use**:
* When the user uninstalls your application
* When transferring a license to another device
* When the user explicitly signs out
**What it does**:
* Removes the device/instance from active activations
* Decrements the activation count
* Frees up a slot for activation on another device
* The license itself remains valid
**Key behaviors**:
* Requires both the license key and instance ID
* Only deactivates the specific instance, not the entire license
* The license can be re-activated on the same or different device
📖 **Full documentation**: [Deactivate License API](https://docs.kelviq.com/api-reference/license/deactivate-license)
***
## 4. Common Workflows
### Workflow A: New Customer Purchase
```
1. Customer purchases a plan with licenses enabled
2. Order is created → License key is automatically generated
3. Customer receives license key (via email, dashboard, etc.)
4. Customer enters key in your application
5. Application calls Activate API
6. License is now active on customer's device
```
For software the customer signs in to, skip steps 3 and 4: read the key from their order or subscription as in [Reading a customer's key](#reading-a-customers-key-from-your-server) and call Activate for them.
### Workflow B: Customer Switches Devices
```
1. Customer uninstalls app from old device (calls Deactivate API)
2. Activation slot is freed
3. Customer installs app on new device
4. Customer enters same license key
5. Application calls Activate API
6. License is now active on the new device
```
### Workflow C: Validating on Application Startup
```
1. Application launches
2. Check if license was previously activated (stored locally)
3. Call Validate API with the license key
4. If valid → Grant access to features
5. If invalid/expired → Prompt user to renew or re-enter key
```
### Workflow D: Admin Extends a License
```
1. Customer requests extension
2. Admin opens the order's License tab
3. Click license menu → "Manage expiry"
4. Select new expiration date
5. Save changes
6. Customer's next validation will reflect the new expiry
```
### Workflow E: Handling a Compromised Key
```
1. Admin notices suspicious activity (too many activations)
2. Open the order's License tab
3. Revoke unauthorized instances
4. If key is widely leaked: Regenerate the key
5. Send new key to legitimate customer
6. Old key stops working immediately
```
***
## Quick Reference
| Task | Where | Action |
| - | - | - |
| Enable licenses for a plan | Plan Details | Toggle "License keys" switch |
| Set activation limit (plan) | Plan Details → License keys | Enable limit + set number |
| Set expiry duration (plan) | Plan Details → License keys | Enable expiry + set duration |
| View customer's license | Order's License tab | See license card |
| Copy license key | Order's License tab | Click on license key |
| Regenerate key | Order's License tab → ⋯ menu | "Regenerate key" |
| Change activation limit | Order's License tab → ⋯ menu | "Edit activation limit" |
| Change expiry date | Order's License tab → ⋯ menu | "Manage expiry" |
| View all activations | Order's License tab | Click license card |
| Revoke a device | License Details | Click "Revoke" on instance |
| Deactivate entire license | Order's License tab → ⋯ menu | "Deactivate" |
***
## Important Notes
⚠️ **Irreversible Actions**:
* **Regenerating a key**: The old key immediately stops working. All existing activations are invalidated.
* **Deactivating a license**: The license is permanently disabled and cannot be reactivated.
✅ **Best Practices**:
* Set reasonable activation limits based on your pricing model
* Use the Validate API on application startup for security
* Store the instance ID locally after activation for proper deactivation
* Communicate expiry dates clearly to customers before they expire
* Consider grace periods before fully blocking expired licenses
# Links
Source: https://docs.kelviq.com/product-catalog/links
Share links with your customers
Links allow you to share important URLs with customers after they purchase your plan. Use links to grant access to communities, resources, or any web-based content.
## Overview
Use Links to share:
* **Community access** – Discord servers, Slack workspaces, or private forums
* **Knowledge bases** – Notion pages, documentation sites, or wikis
* **Membership portals** – Member-only websites or dashboards
* **Resource libraries** – Google Drive folders, Dropbox links, or online courses
* **Any other web content** your customers need access to
## Accessing Links
1. Navigate to **Products** in the sidebar
2. Select the product containing your plan
3. Click on the plan you want to edit
4. Scroll down to the **Links** section
5. Click the expand arrow to open the section
The section header shows the current count of saved links (e.g., "Links (3)").
## Adding Links
### How to Add a Link
1. Open the **Links** section
2. You'll see two input fields:
* **Link name** – A descriptive name for the link
* **Link URL** – The full URL starting with `https://`
3. Enter the link name (e.g., "Private Discord community")
4. Enter the full URL (e.g., `https://discord.gg/your-invite`)
5. Click **+ Add link** to add another row if needed
6. Click **Save** to save all links
### Link Name Examples
Choose clear, descriptive names that tell customers what they'll access:
| Good Examples | Why It Works |
| - | - |
| Private Discord Community | Clear destination |
| Course Materials (Notion) | Describes content and platform |
| Member Dashboard | Indicates exclusive access |
| Resource Library | Explains what's inside |
### URL Requirements
* URLs must start with `https://` or `http://`
* URLs must be valid and properly formatted
* Each link requires both a name and URL to be saved
## Managing Links
### Edit Existing Links
1. Open the **Links** section
2. Modify the link name or URL directly in the input fields
3. Click **Save** to update
### Remove a Link
1. Open the **Links** section
2. Click the **×** button next to the link you want to remove
3. Click **Save** to confirm the removal
### Cancel Changes
If you've made changes but want to discard them:
1. Click **Cancel**
2. All unsaved changes will be reverted to the last saved state
## Customer Experience
After a successful purchase, customers can:
1. Access the order confirmation page
2. View all links associated with their purchased plan
3. Click any link to open it in a new tab
Links remain accessible to customers as long as their subscription or purchase is active.
# Location based pricing
Source: https://docs.kelviq.com/product-catalog/location-based-pricing
Set custom prices for specific countries to optimize global conversion
Location based pricing is a feature that allows you to set custom prices for specific countries to optimize global conversion.
## Set up localized prices
To offer a localized price open your plan configuration and expand the Price localization card.
> [!NOTE]
>
> Regional prices inherit the base price's usage reset, usage alert, and credit rollover settings. Regional pricing changes the localized monetary price; it does not create a separate usage-policy configuration.
### 1. Choose a currency
Select your target currency from the dropdown list. You can choose options like Euro or Indian Rupee. Click Add localized price to open the configuration panel.
### 2. Set the fixed base charge
Kelviq automatically displays the billing cycles you already enabled for your default base price and usage based pricing. Enter the exact localized amount you want to charge for each active interval.
### 3. Localize usage based features
If your plan includes Meter features like API calls Kelviq pulls those in automatically right below the fixed charge section. You can set localized unit prices and flat fees for every single usage tier.
You must configure these usage rates across all active billing periods. Use the tabs to switch between your monthly and yearly configurations and ensure every input has a defined price.
### 4. Save and stack regions
Click Save to lock in the location based pricing configuration. The currency will appear in your localized pricing list.
You can repeat this process to add as many localized currencies as you need.
## Fraud protection
Kelviq analyzes the IP address, browser fingerprint, and issuing bank of the credit card during checkout. If a customer attempts to use a card from a high income country while pretending to be in a lower income region we block the transaction or force the standard global price automatically.
# One time payments
Source: https://docs.kelviq.com/product-catalog/one-time-payments
Charge a flat fee for lifetime access or digital downloads
Not every product needs a subscription. If you are selling a lifetime software license, a template, or charging a one time setup fee for an AI agent, you use a flat base price.
## Set up a one time price
1. Open your draft plan and ensure it is set to Paid
2. Under the billing cycles select One time
3. Enter the total amount you want to charge
4. Click Save
> [!NOTE]
>
> One-time payments do not support free trials. To offer a trial, add and enable a recurring billing cycle on the plan.
Customers pay this amount exactly once during checkout. If you attach digital downloads or license keys to this plan they gain permanent access to those assets immediately after payment.
If an existing customer already has a saved payment method, you can also [create a one-time charge from your backend](/sales/create-a-one-time-charge) without sending them through checkout again.
## Combine with usage
Pay as you go usage is billed monthly, so it can't be added to a One Time price. To charge a fixed fee plus usage, use a **Monthly** price and add a Pay as you go usage charge. See [Pay as you go](/product-catalog/pay-as-you-go).
# Pay as you go
Source: https://docs.kelviq.com/product-catalog/pay-as-you-go
Bill customers each month for the usage they record
With pay as you go, the customer does not buy a block of usage upfront. Your backend reports what they consume, and Kelviq bills the resulting amount at the end of the monthly subscription period. Use it for API calls, AI tokens, storage, compute time, or any other metered cost.
The same plan can contain a monthly base price and one or more usage charges. You define the billable feature and its rates in the dashboard; your application supplies the usage.
> [!NOTE]
>
> Monthly must be the plan's only billing period. Pay as you go can't be used on a plan that also offers yearly, quarterly, one-time, or another billing period.
## Before you start
You will need:
* A product and a plan in Kelviq
* A [Meter feature](/product-catalog/create-a-feature), such as `api-calls` or `tokens`
* A monthly price on the plan
* A server API key for the same environment as the plan
Pay as you go supports **Flat**, **Package**, **Tiered**, and **Volume** pricing. It does not support **Stair-step** pricing.
## Configure the plan
1. Open the product and edit its plan.
2. In the plan's billing periods, keep **Monthly** enabled and turn off every other period.
3. Open **Usage charges** and select the Meter feature you want to bill for. If the list is empty, [create a Meter feature](/product-catalog/create-a-feature) from **Product catalog → Features** first.
4. For **Billing model**, choose **Pay-as-you-go**.
5. Choose a pricing model and enter its rates.
6. Add [usage alerts](/product-catalog/usage-alerts) if you want to notify your application when usage crosses a threshold.
7. Save the plan. If you edited a published plan, publish the new version before testing it.
When you select Pay as you go, Kelviq keeps Monthly as the plan's only billing period. Usage reset and credit rollover controls are removed because there is no prepaid balance to reset or carry into the next period.
## Choose a pricing model
The billing model controls *when* the customer pays. The pricing model controls *how* Kelviq calculates the charge.
| Pricing model | How it bills | Example |
| - | - | - |
| Flat | Uses one rate for every unit | \$0.001 per API call |
| Package | Bills in blocks of units | \$2 per 10,000 tokens |
| Tiered | Applies each rate only to the units inside that tier | First 100,000 tokens free, then \$0.0002 per token |
| Volume | Uses the rate for the customer's final usage band across all units | \$0.01 per request, or \$0.007 for all requests after 100,000 |
See [Usage-based pricing](/product-catalog/usage-based-billing) for the full calculation rules and examples for each model.
### Combine a base price with usage
You can charge a fixed monthly subscription and add usage on top. For example:
```text theme={null}
Base subscription: $20 per month
Included usage: 100,000 tokens
Additional usage: $0.0002 per token
```
If the customer uses 120,000 tokens, the first 100,000 fall into a zero-priced tier. The remaining 20,000 tokens cost \$4, so the period total is \$24 before tax.
## Report usage from your backend
Kelviq can only bill usage that your application reports. Send usage from trusted server-side code after the billable action succeeds. Do not expose a server API key in browser or mobile code.
### Node.js
Use `DELTA` when each call adds to the current meter:
```ts theme={null}
import { BEHAVIOUR_CHOICES, Kelviq } from "@kelviq/node-sdk";
const client = new Kelviq({
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
});
await client.reporting.reportUsage({
customerId: "customer_001",
featureId: "api-calls",
value: 1,
behaviour: BEHAVIOUR_CHOICES.DELTA,
});
```
Use `SET` when you already maintain a cumulative total and want Kelviq's meter to match it:
```ts theme={null}
await client.reporting.reportUsage({
customerId: "customer_001",
featureId: "api-calls",
value: 1250,
behaviour: BEHAVIOUR_CHOICES.SET,
});
```
| Field | What to send |
| - | - |
| `customerId` | The same customer identifier used for the subscription |
| `featureId` | The identifier of the Meter feature on the plan |
| `value` | A whole-number usage quantity |
| `behaviour` | `DELTA` to add usage or `SET` to replace the current value |
> [!WARNING]
>
> A repeated `DELTA` call adds the value again. Make sure retries do not submit the same unit of work twice. If your system periodically sends an authoritative running total, use `SET` instead.
### REST API
You can send the same update without an SDK:
```bash theme={null}
curl --request POST \
--url https://api.kelviq.com/api/v1/report/usage/ \
--header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"customerId": "customer_001",
"featureId": "api-calls",
"value": 1,
"behaviour": "DELTA"
}'
```
See [Report pre-aggregated usage](/api-reference/reporting/report-pre-aggregated-usage) for the request and response schema.
## How billing works
1. The customer starts a monthly subscription.
2. Your backend reports usage throughout the period.
3. Kelviq updates the meter whenever it receives a valid report.
4. At the end of the subscription period, Kelviq applies the configured pricing rules to the final usage.
5. The meter starts a new monthly period on the customer's subscription renewal date.
Reporting usage does not charge the customer immediately. It updates the quantity Kelviq will use for the period's bill.
## Add alerts without stopping usage
Usage alerts are optional, but they are useful when a bill can grow during the month. You can set absolute thresholds for a pay-as-you-go feature, then handle the `feature.usage_alert` webhook to send an email, show an in-app warning, or suggest a different plan.
You do not need a separate pay-as-you-go webhook to calculate the bill. Usage reports drive the meter; alerts only notify your application when a threshold is crossed.
See [Usage alerts](/product-catalog/usage-alerts) for configuration and webhook examples.
## Test in sandbox
Sandbox and production have separate products, customers, subscriptions, and API keys. To test the complete flow:
1. Switch the dashboard to Sandbox.
2. Create or publish a monthly plan with a pay-as-you-go charge.
3. Complete a test checkout so the sandbox customer has an active subscription.
4. Initialize the Node SDK with `environment: "sandbox"`, or send REST requests to `https://sandboxapi.kelviq.com/api/v1`.
5. Report a small usage value.
6. Open the customer's metered entitlement and confirm that the recorded usage changed as expected.
See [Sandbox](/guides/sandbox) for environment setup and test-payment details.
## Troubleshooting
### Pay as you go shows a billing-period error
Remove every billing period except Monthly. A plan with both Monthly and Yearly pricing is not eligible, even if you only enter a usage rate under Monthly.
### Stair-step cannot be selected
Stair-step pricing is not available with Pay as you go. Choose Flat, Package, Tiered, or Volume. If you need fixed usage bands, use an advance commitment instead.
### Reported usage does not appear
Check that the API key, customer, plan, and feature all belong to the same environment. Also confirm that `customerId` and `featureId` exactly match the identifiers in Kelviq.
### Usage is too high
Look for duplicate `DELTA` calls or a mismatch between the unit your code reports and the unit your price expects. For package pricing, remember that a partially used package is billed as a complete package.
### Credit rollover is missing
This is expected. Rollover applies to unused advance-commitment credits, not usage billed after the period ends.
# Plans
Source: https://docs.kelviq.com/product-catalog/plans
Configure pricing, features, and deliverables
A plan is the commercial package you offer to customers. It bundles your pricing logic with the actual value you deliver, such as software downloads, community access, or feature limits.
You can create multiple plans for a single product. For example, you might have a "Starter" plan for hobbyists and a "Pro" plan for businesses.
For sales-led pricing, see [Create an Enterprise plan](/product-catalog/create-an-enterprise-plan). It covers both reusable Enterprise tiers and bespoke customer amounts.
## Plan structure
Every plan consists of configurable components that define what the user gets.
> **Pricing**
>
> Define the cost. Choose between recurring subscriptions (monthly/yearly) or one-time lifetime payments.
> **License keys**
>
> Issue software licenses. Generate unique keys upon purchase and enforce activation limits.
> **Features & limits**
>
> Set limits. Control access to specific features, API quotas, or seat limits via the SDK.
> **Downloads**
>
> Attach files. Upload software binaries, e-books, or course content.
> **Links**
>
> Grant access. Direct customers to private Discord servers or Notion templates.
## Plan lifecycle
You manage plans through a simple status flow.
* **Draft**
The default state for new plans. These are not visible to customers.
* **Published**
The plan is live and checkout is enabled.
* **Unpublished changes**
A draft version of an existing published plan. You are editing a copy, so your live plan remains safe until you hit publish again.
* **Archived**
The plan is hidden from new customers but remains active for existing subscribers.
***
## Create a plan
You create plans directly inside a product container.
**1. Start creation**
Navigate to the **Product detail page** and click **+ Create plan**.
**2. Define basics**
Fill in the plan details.
* **Plan name:** The public name (e.g. "Pro", "Starter").
* **Identifier:** The unique ID used in your code. You can override the auto-generated ID.
* **Description:** Optional text shown on invoices and checkout.
> [!TIP]
>
> Enable the **Create more** toggle to quickly add multiple plans in a row without closing the modal.
**3. Save draft**
Click **Create**. The plan will appear in your list with a **Draft** badge.
***
## Configure pricing
Click on any draft plan to enter the configuration view. The first step is to set how you charge.
## Pricing models
Once your plan draft exists you can configure how you charge. We split these into dedicated guides.
* [One time payments](/product-catalog/one-time-payments)
* [Subscriptions](/product-catalog/subscriptions)
* [Enterprise and bespoke plans](/product-catalog/create-an-enterprise-plan)
* [Seat based pricing](/product-catalog/seat-based-pricing)
* [Usage-based pricing](/product-catalog/usage-based-billing)
* [Free plans and trials](/product-catalog/free-and-trials)
* [Location based pricing](/product-catalog/location-based-pricing)
### Free vs. Paid
Use the toggle in the top right to switch between a free or paid plan.
* **Free plan:** Users are not charged. Useful for lead magnets or open-source tiers.
* **Paid plan:** Unlocks the billing configuration options below.
### Billing cycles
Select the intervals you want to offer. You can enable multiple intervals for a single plan.
* **28 days:** A recurring four-week subscription.
* **Monthly / Yearly:** Standard recurring subscriptions.
* **3 Months:** Quarterly billing.
* **6 Months:** Billing twice a year.
* **One time:** A single non-recurring payment (lifetime deal).
The 28-day period is useful when you need a consistent four-week renewal schedule rather than a calendar-month renewal.
> [!TIP]
>
> To test a renewal without waiting a full month, ask support to enable daily billing for your sandbox. See [Test a subscription renewal](/guides/sandbox#test-a-subscription-renewal).
### Location based pricing
You can set specific prices for different countries rather than relying on auto-conversion.
1. Click **+ Add localized price**.
2. Select the currency (e.g. EUR, INR).
3. Enter the price for that market.
***
## Add deliverables
Configure what the customer receives immediately after purchase. These assets are delivered directly via the customer portal or email.
### Digital downloads
Upload files that are securely delivered after purchase.
1. Expand the **Digital downloads** accordion.
2. Drag and drop your files (up to 5GB total).
3. Customers will see these in their portal immediately after checkout.
### License keys
If you are selling software that requires activation, you can issue unique license keys.
1. Expand the **License keys** accordion.
2. **Activation limit:** Set how many machines or instances can use a single key (e.g. 1 for personal, 5 for team).
3. **License duration:** Define how long the key remains valid (e.g. 1 Year).
### Links
Provide access to resources hosted elsewhere.
1. Expand the **Links** accordion.
2. Add the **Link name** (e.g. Private Discord community).
3. Add the **Link URL**.
***
## Features & limits
Configure feature access, usage quotas, and API limits.
* **Toggle features:** Turn specific capabilities on or off (e.g. "SSO Access").
* **Numeric limits:** Set quotas (e.g. "5 Projects", "10,000 API calls").
***
## Publishing & Versioning
We protect your live customers by creating a separate version when you edit a plan.
### How it works
* **Safe editing**
When you edit a **Published** plan, we automatically create a new **Unpublished** version. Your live plan remains untouched so customers can keep buying without interruption.
* **Unpublished changes**
You will see a yellow badge indicating you are working on a draft version. You can make as many changes as you want here without affecting the live site.
* **Publishing**
When you click **Publish**, this new version replaces the old one.
### Pushing updates
Because the new version replaces the old one, you need to decide what happens to your current subscribers.
When you click **Publish**, we will ask you to confirm the rollout strategy.
* **For price changes:** You decide whether to grandfather existing users on the old price or migrate them to the new one.
* **For feature changes:** You decide whether to push the new entitlements to existing users immediately or keep them on their legacy configuration.
If you grandfather existing customers, they keep their current price and only new customers see the updated price. If you migrate existing customers, the new price applies to their future renewals.
Most recurring card and debit-card payments do not require the customer to approve the new price again. Some payment methods have additional rules. For example, an Indian UPI AutoPay mandate may require the customer to approve a renewal when the updated amount exceeds the applicable regulatory threshold.
If you change your mind while editing, you can click **Discard** to delete the unpublished version and revert to the live state.
### Plan actions
Click the **⋯** menu next to the **Publish** button (**Publish updates** on a plan with unpublished changes) to see more options.
| Action | Description |
| - | - |
| **Edit** | Open the plan configuration to make changes |
| **Get Link** | Copy the direct checkout link for this plan |
| **Country restrictions** | Limit which countries can purchase this plan |
| **Tax behavior** | Choose whether prices include tax or tax is added at checkout |
| **Delete** | Remove the plan |
| **Restore last published version** | Shown on a plan with unpublished changes. Discard unpublished changes and revert to the live version |
| **View published version** | Shown on a plan with unpublished changes. Preview what customers currently see on the live plan |
# Products
Source: https://docs.kelviq.com/product-catalog/products
Create and manage your high-level product containers
A product is the top-level container for what you sell. It groups together your pricing plans, features, and assets into a single family.
Before you can create plans or configure billing logic, you need to define the product they belong to.
## Create a product
Follow these steps to set up a new product.
**1. Go to Products**
Navigate to **Product Catalog > Products** in the sidebar.
**2. Start creation**
Click **+ Create product** in the top right corner.
**3. Enter details**
Fill out the basic information for your product.
* **Product name** — The public name shown to customers, such as “Pro Templates”.
* **Description** — A short summary of the offering.
* **Media** — Upload up to 10 images to showcase the product on checkout. We recommend a 4:3 aspect ratio (1600 × 1200 px).
Kelviq assigns an internal UUID when the product is created. You do not need to create or manage a separate product identifier in the dashboard.
**4. Finish**
Click **Create**. You will be redirected to the product details page.
## Next steps
Now that you have a product container, you can define the pricing plans and deliverables inside it.
# Proration
Source: https://docs.kelviq.com/product-catalog/proration
What a customer pays when they change plans in the middle of a billing period
When a customer changes plans mid-period, proration decides what they pay for the time left. Kelviq credits the unused part of the old plan and charges for the rest of the period on the new plan. You choose whether that difference is charged now, added to the next invoice, or skipped.
Both examples below use monthly plans, with the change made exactly halfway through the month.
## Upgrade: \$100 → \$200
The unused half of the old plan is worth a \$50 credit. The remaining half of the new plan costs \$100. The difference is \$50.
| Option | Today | Next renewal |
| - | - | - |
| **Immediate charge** | \$50 charged | \$200 |
| **Prorate on next invoice** | Nothing | \$200 + \$50 = \$250 |
| **No proration** | Nothing | \$200 |
## Downgrade: \$200 → \$100
The unused half of the old plan is worth a \$100 credit. The remaining half of the new plan costs \$50. The customer is owed \$50.
| Option | Today | Next renewal |
| - | - | - |
| **Immediate charge** | Nothing; \$50 is kept as account credit | \$100, less the \$50 credit = \$50 |
| **Prorate on next invoice** | Nothing | \$100 − \$50 = \$50 |
| **No proration** | Nothing | \$100 |
The new plan and its limits apply as soon as the change is made, whichever option you pick. Amounts depend on the exact time of the change.
## Set your defaults
Open **Settings → Subscription proration**. There are two defaults:
| Setting | Applies to | Default |
| - | - | - |
| **Plan upgrades & downgrades** | A customer moving to a different plan | Immediate charge |
| **Plan version migrations** | Moving customers to a new version of the same plan | Prorate on next invoice |
> [!WARNING]
>
> Switching between monthly and yearly billing always invoices immediately, whatever you choose here. The change starts a new billing period and sets the new renewal date. With **No proration**, unused time on the old interval isn't credited.
## Override per change
Pass `prorationBehavior` when you update a subscription through the API or SDK. It overrides the default for that change.
| Value | Dashboard name |
| - | - |
| `IMMEDIATE_CHARGE` | Immediate charge |
| `PRORATE_NEXT_INVOICE` | Prorate on next invoice |
| `NO_PRORATION` | No proration |
```ts theme={null}
import { CHARGE_PERIOD_CHOICES, PRORATION_BEHAVIORS } from '@kelviq/node-sdk';
await client.subscriptions.update({
subscriptionId: 'sub_123',
planIdentifier: 'pro',
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
prorationBehavior: PRORATION_BEHAVIORS.PRORATE_NEXT_INVOICE,
});
```
To see the exact amounts before you commit, call `client.subscriptions.previewUpdate` with the same fields, or `POST /subscriptions/{subscriptionId}/update/preview/`.
To keep the old plan until the customer pays for the new one, see [Wait for payment before changing access](/product-catalog/subscriptions#wait-for-payment-before-changing-access).
# Seat based pricing
Source: https://docs.kelviq.com/product-catalog/seat-based-pricing
Charge teams for the number of seats they purchase
Seat based pricing ties the subscription price to the number of people who can use an account. A team that buys eight seats pays for eight, even if only six are occupied today.
This guide covers seats purchased in advance. The chosen quantity is included when you create checkout, and your application uses the resulting entitlement as its team-size limit.
> [!NOTE]
>
> If you want to bill for the number of seats that were actually active during the month, use [pay as you go](/product-catalog/pay-as-you-go) instead. Report the active-seat total with `SET` and let Kelviq bill it at the end of the period.
## How the price is calculated
A plan can consist entirely of seat charges or combine them with a fixed base price.
```text theme={null}
Monthly base price: $20
Price per seat: $12
Seats purchased: 8
Monthly subtotal: $20 + ($12 × 8) = $116
```
Kelviq carries the seat quantity from checkout into the subscription. The resulting entitlement tells your application how many seats the customer purchased.
## Create the seat feature
These steps create a Meter feature specifically for seats. For the general dashboard and API workflows, see [Create a feature in Kelviq](/product-catalog/create-a-feature).
1. Open **Product catalog → Features**.
2. Click **Create feature**.
3. Enter a clear name such as `Seats`.
4. Use a stable identifier such as `seats`.
5. Select **Meter** as the feature type.
6. Set the singular unit to `seat` and the plural unit to `seats`.
7. Create the feature.
Use a Meter feature rather than a Customizable feature. Kelviq can attach a price to the Meter feature and accept its quantity during checkout.
> [!NOTE]
>
> Purchased-seat pricing does not require usage reports. Although Seats is a Meter feature, its billable quantity comes from checkout and subscription updates.
## Add the seat price to a plan
1. Open the product and edit the plan you want to sell.
2. Make the plan **Paid** and select its billing periods, such as Monthly and Yearly.
3. Enter the plan's base price. Use this for the fixed part of the subscription, if any.
4. Open **Usage charges**.
5. Select the `seats` feature.
6. For **Billing model**, choose **Advance commitment**. The customer is purchasing the seats before using them.
7. For **Pricing model**, choose **Flat** for a standard per-seat price.
8. Enter the price per unit for every billing period. For example, use `$12` under Monthly and `$120` under Yearly.
9. Save the price and publish the plan.
The seat rate belongs under Usage charges even though this is not usage billed in arrears. **Advance commitment** is what makes the selected quantity an upfront seat purchase.
## Other ways to price seats
Most teams start with one price per seat. You can also sell seats in packages, lower the rate at higher quantities, or charge a fixed amount for each range.
| Pricing model | Seat calculation | Example |
| - | - | - |
| Flat | Every seat has the same price | 8 seats × \$12 = \$96 |
| Package | Seats are sold in fixed-size packs | \$50 for each block of 5 seats |
| Tiered | Each range of seats uses its own rate | Seats 1–10 at \$15, then seats 11–25 at \$12 |
| Volume | The final seat count sets the rate for every seat | 1–10 seats at \$15 each; 11+ seats at \$12 each |
| Stair-step | The seat count selects one fixed charge | \$100 for up to 10 seats; \$220 for up to 25 |
See [Usage-based pricing](/product-catalog/usage-based-billing) for the calculation rules for Package, Tiered, Volume, and Stair-step pricing.
## Send the seat count to checkout
Kelviq's pricing UI can show a quantity input for a priced Meter feature. If you build your own pricing page, send the selected seat count in the checkout request.
### Node.js
```ts theme={null}
import { CHARGE_PERIOD_CHOICES, Kelviq } from "@kelviq/node-sdk";
const client = new Kelviq({
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
});
const seatCount = 8;
const session = await client.checkout.createSession({
planIdentifier: "team-plan",
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
customerId: "customer_001",
successUrl: "https://app.example.com/billing/success",
features: [
{
identifier: "seats",
quantity: seatCount,
},
],
});
return Response.redirect(session.checkoutUrl);
```
### REST API
```bash theme={null}
curl --request POST \
--url https://api.kelviq.com/api/v1/checkout/ \
--header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"planIdentifier": "team-plan",
"chargePeriod": "MONTHLY",
"customerId": "customer_001",
"successUrl": "https://app.example.com/billing/success",
"features": [
{
"identifier": "seats",
"quantity": 8
}
]
}'
```
The `features` array uses the feature identifier, not its dashboard UUID. `quantity` is the number of seats the customer wants to purchase.
> [!WARNING]
>
> Create the checkout session on your backend. Validate that the quantity is a positive whole number, and never expose the Server API Key in browser code.
See [Create a checkout session](/api-reference/checkout/create-a-checkout-session) for the full request schema.
## Enforce the purchased limit
After payment and subscription creation, read the customer's seat entitlement from your backend. For a Meter feature, `usageLimit` is the purchased capacity.
```ts theme={null}
const entitlement = await client.entitlements.getEntitlement({
customerId: "customer_001",
featureId: "seats",
});
const purchasedSeats = entitlement?.usageLimit ?? 0;
const activeMembers = await db.teamMember.count({
where: { teamId: "team_001", status: "active" },
});
if (activeMembers >= purchasedSeats) {
throw new Error("No seats available. Add another seat before inviting a member.");
}
```
Check the limit when the team owner sends or accepts an invitation. A frontend-only check is easy to bypass, so keep the final enforcement on your server.
`hasAccess` answers whether the customer can use the feature. It does not tell you whether one more team member fits. Compare your active member count with `usageLimit` for that decision.
## Change the seat count
Use the subscription update endpoint when a customer adds or removes seats. Send the complete new quantity, not the difference from the old quantity.
```ts theme={null}
import { CHARGE_PERIOD_CHOICES } from "@kelviq/node-sdk";
await client.subscriptions.update({
subscriptionId: "dffaf07e-4517-47db-ba3a-59a05aa2d465",
planIdentifier: "team-plan",
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
features: [
{
identifier: "seats",
quantity: 12,
},
],
});
```
The update request still needs `planIdentifier` and `chargePeriod`, even when the plan is not changing. After the request succeeds, read the entitlement again before making the additional capacity available.
Before reducing a subscription below the current team size, ask the customer to remove or deactivate members. Otherwise, the subscription and your application's active-member count will disagree.
See [Update a subscription](/api-reference/subscriptions/update-a-subscription) for the complete API request.
## Purchased seats versus active seats
Choose one source of truth for billing.
| Model | Where the quantity comes from | When the customer pays |
| - | - | - |
| Purchased seats | Checkout and subscription updates | At the start of the billing period |
| Active seats | Usage reported by your backend | At the end of each monthly period |
For active-seat billing, configure the Seats feature as Pay as you go and send the current active-seat total with `SET`. Do not send both a purchased quantity and usage reports for the same seat charge, or the two models will conflict.
## Seats are not license activations
A seat normally represents a member of a team or workspace. A license activation represents a device or software installation.
Use seat based pricing when the customer pays for people who can join an account. Use [license keys](/product-catalog/license-keys) when you need to limit how many devices can activate downloaded software. A single customer may use both, but they should have separate limits.
## Test in sandbox
1. Switch the dashboard to Sandbox.
2. Create the Seats feature and a seat based plan there.
3. Create a checkout session with a small quantity, such as 3.
4. Confirm that checkout shows the expected base and seat charges.
5. Complete the test payment.
6. Read the `seats` entitlement and confirm that its limit matches the purchased quantity.
7. Update the subscription to 5 seats and check the entitlement again.
Sandbox and production use separate catalog data and API keys. See [Sandbox](/guides/sandbox) before moving the integration to production.
## Troubleshooting
### The total does not change with the seat count
Confirm that Seats is a Meter feature, that it has a price under Usage charges, and that the checkout request includes the exact `seats` identifier in `features`.
### The quantity input is missing
Publish the latest version of the plan and check that the seat feature is enabled and priced for the selected billing period.
### The entitlement has the wrong limit
Check that the checkout, customer, plan, and API key belong to the same environment. Then inspect the checkout or subscription request and confirm that `quantity` contains the complete desired seat count.
### A team can exceed its purchased seats
Kelviq stores the entitlement, but your application must enforce it when members are invited or activated. Compare the active-member count with `usageLimit` on your backend.
### A seat reduction would leave too many active members
Do not remove members automatically unless your product explicitly promises that behavior. Ask a team owner to choose which members lose access, then submit the lower quantity.
# Subscriptions
Source: https://docs.kelviq.com/product-catalog/subscriptions
Set up recurring billing and understand renewals and failed payments
Subscriptions are the default for traditional SaaS products. You charge customers on a regular schedule to maintain access to your application.
## Set up recurring billing
1. Open a draft plan and make sure it is set to **Paid**.
2. Under **Billing cycles**, select the recurring intervals you want to offer, such as **28 days**, **Monthly**, **3 Months**, **6 Months**, or **Yearly**.
3. Enter the price for each interval.
4. Click **Save**.
You can enable multiple intervals on one plan. Customers choose among the enabled intervals at checkout.
> [!NOTE]
>
> A 28-day subscription renews every four weeks. It is not the same as a calendar-month subscription. If the **28 days** option is not visible for your organization, contact Kelviq support to have it enabled.
## Subscription lifecycle
Kelviq handles recurring payments automatically. This includes:
* Charging the saved payment method at the end of each billing cycle
* Sending receipts and tax invoices
* Retrying failed card payments
* Applying prorated charges when a customer changes plans during a billing cycle
Check the current subscription status with the Kelviq SDK or API. If your application needs event notifications, use [webhooks](/guides/webhooks).
## Change a subscription
By default, plan upgrades and downgrades take effect immediately. As soon as the change is processed, Kelviq applies the new plan and its feature limits.
For a paid change, you can wait until payment succeeds before activating the new plan. Pass `paymentBehavior: "activate_on_payment"` when you update the subscription:
```json theme={null}
{
"planIdentifier": "premium-plan",
"chargePeriod": "MONTHLY",
"paymentBehavior": "activate_on_payment"
}
```
Omit `paymentBehavior` to keep the default immediate-update behavior.
### Control how a change is billed
Proration decides what the customer pays for the rest of the period: charged now (`IMMEDIATE_CHARGE`), added to the next invoice (`PRORATE_NEXT_INVOICE`), or skipped (`NO_PRORATION`). Set your defaults in **Settings → Subscription proration**, or pass `prorationBehavior` when you update a subscription.
[Proration](/product-catalog/proration) walks through each option with an upgrade and a downgrade example. The defaults are also available through the API as `updateSubscriptionProrationBehavior` and `migrateSubscriptionProrationBehavior` on `PATCH /organizations/settings/`.
### Wait for payment before changing access
`activate_on_payment` keeps the customer's current subscription active while payment for the change is pending. This prevents an unpaid plan change from replacing working access.
| Payment stage | Current subscription | Updated subscription |
| - | - | - |
| A saved card is charged successfully without customer action | Changes to `superseded` | Changes to `active` |
| UPI, a 3DS card, or another method requires customer action | Remains `active` | Starts as `incomplete` |
| The customer completes payment | Changes to `superseded` | Changes to `active` |
| The immediate charge fails, or the customer does not complete payment before expiry | Remains `active` | Changes to `incomplete_expired` |
Card payments that do not require authentication are usually completed during the update request, so the status change can happen immediately. When the payment method requires customer action, continue using the existing subscription until the updated subscription becomes `active`.
> [!WARNING]
>
> A successful update API response does not always mean the new plan is active. When you use `activate_on_payment`, check the subscription status or the customer's current entitlements before granting access to the new plan.
### Upgrades
Under the default `IMMEDIATE_CHARGE` proration behavior, Kelviq prorates the price change against the time left in the current billing period. It credits the unused portion of the old plan, charges for the remaining portion of the new plan, and collects the net difference. See [Control how a change is billed](#control-how-a-change-is-billed) for the other options.
With `activate_on_payment`, Kelviq waits for that payment to succeed before activating the upgraded plan.
For example, if a customer moves from a \$100 monthly plan to a \$200 monthly plan halfway through the period, the approximate calculation is:
| Item | Amount |
| - | -: |
| Unused half of the old plan | -\$50 credit |
| Remaining half of the new plan | \$100 charge |
| Net amount collected | \$50 |
The exact amount depends on when the upgrade is processed. Existing usage counters are retained and evaluated against the new plan's limits.
### Downgrades
Under the default payment behavior, downgrades also apply immediately. If the customer has unused value on the higher-priced plan, Kelviq converts it to account credit and applies that credit to future invoices.
> [!WARNING]
>
> An immediate downgrade can lower a customer's limits below their current usage. Check the customer's entitlements after the change and decide how your application should handle any over-limit state.
## Cancel a subscription
When cancelling, choose whether the subscription should end immediately or at the end of the current billing period. A plan downgrade and a subscription cancellation are separate actions: the downgrade follows the payment behavior you choose, while the cancellation follows the timing option you select.
## Pause a subscription
A paused subscription stops billing and stops access. The customer isn't charged, their entitlements return `hasAccess: false`, and plan changes are blocked until the subscription resumes. Cancelling stays available.
Customers pause from the [customer portal](/customer-portal/overview) when a [retention offer](/customer-portal/retention) includes a pause. They choose 1, 3, or 6 months.
A pause has to cover at least one full billing period, so a 1-month pause on a yearly plan is refused. Only an `active` subscription can be paused, not one on trial, past due, already paused, or scheduled to cancel. Free and manually billed subscriptions can't be paused.
### Resume a subscription
A paused subscription resumes on its own at the end of the pause. Choose what happens on resume in **Settings → Retention → Advanced settings**:
| | Reset billing cycle (default) | Keep billing day |
| - | - | - |
| Charged on resume | A full period | Nothing |
| Next charge | One period after the resume date | The original billing day |
| Billing day afterwards | The resume date | Unchanged |
For a monthly plan billed on the 1st, paused on 10 September and resumed on 20 October, reset charges a full month on 20 October and bills on the 20th from then on. Keep billing day charges nothing and bills on 1 November as before, which gives the customer free access from the 20th to the 1st. A customer who resumes inside a period they've already paid for is never charged again, whichever behavior you pick.
On resume, entitlements come back with usage reset to zero and a fresh period.
### What changes while paused
The subscription has `status: "paused"`, `pausedAt`, and `pauseResumesAt` (`null` for an open-ended pause). Kelviq sends `subscription.paused` and `subscription.resumed` [webhooks](/guides/webhooks), whichever surface the change came from. Webhook payloads use snake\_case, so the same fields arrive there as `paused_at` and `pause_resumes_at`. Renewals that would fall inside the pause are skipped silently, so a paused subscription sends no other events until it resumes.
If you cache entitlement checks, clear them when you receive `subscription.paused`, otherwise the customer keeps access until the cache expires. Both SDKs have a call for it: `client.entitlements.invalidateCache({ customerId })` in Node and `client.entitlements.invalidate_cache(customerId=...)` in Python.
### Retention offers
Before a customer cancels, you can offer them a reason to stay. In the dashboard retention settings, switch retention on and map each cancellation reason to an offer:
* **Discount**: a percentage off for a set number of billing cycles, applied as a single-use coupon.
* **Pause**: a break of one of the lengths you allow. Billing and access stop, then resume on a renewal boundary.
* **Support**: a link to a booking page or support form, for reasons a conversation can fix.
The customer portal shows these offers automatically. To build the same flow in your own app, call [Get retention offers](/api-reference/subscriptions/get-retention-offers) for the subscription. It returns every cancellation reason with its configured offer and whether this subscription is eligible for it right now, so you can show an unavailable offer greyed out with a reason. When the customer takes an offer, call [Accept a retention offer](/api-reference/subscriptions/accept-a-retention-offer) with the reason and the offer. If they cancel anyway, call [Cancel a subscription](/api-reference/subscriptions/cancel-a-subscription) with the same reason as `cancellationFeedback`.
> [!NOTE]
>
> An offer must be the one configured for the reason the customer picked, and eligibility is checked again when it is accepted. The repeat policy you set decides whether a customer who has already taken an offer can be offered it again, so discounts cannot be stacked by reopening the cancellation flow.
## Refund a cancelled subscription
Kelviq does not automatically refund unused time when a subscription is cancelled mid-period. You decide whether to issue a full refund, a partial refund, or no refund.
For a usage-based subscription, calculate the refund under your own policy using the customer's consumed usage and remaining time. Kelviq does not currently calculate usage-adjusted refunds for you. Once you decide the amount, open the corresponding order in the dashboard and issue the full or partial refund there.
## Failed subscription payments
A failed automatic card payment does not cancel the customer's payment authorization. Kelviq can use the same authorization for later attempts and future billing cycles.
If the customer pays the failed card invoice manually, automatic payments remain active. Kelviq will still use the saved payment method for the next billing cycle.
### Card payment retries
When an automatic card payment fails, the subscription moves to `past_due`. Kelviq retries the payment up to eight times over the next 14 days. If recovery is unsuccessful, Kelviq cancels the subscription.
After each failed attempt, Kelviq emails the customer a link to pay the invoice. The customer can also use the [Customer Portal](/customer-portal/managing-payment-methods) to update their payment method.
You do not need to schedule retries, send card payment links, or ask the customer to set up automatic payments again. Kelviq handles this recovery flow.
> [!NOTE]
>
> This retry schedule applies only to cards. Kelviq does not retry a failed non-card renewal or send a recovery payment link. The subscription is canceled after the payment fails.
# Tax settings
Source: https://docs.kelviq.com/product-catalog/tax-settings
Configure price display rules and B2B exemptions
You manage your tax configuration in two places. You set how prices display on individual plans and you set how business exemptions are handled globally.
## Plan tax behavior
By default Kelviq adds tax on top of your listed price at checkout. If you want customers to see the final price upfront you can enable tax inclusive pricing. You configure this per plan.
To change how prices are displayed open your plan draft. Click the menu icon next to the Publish button and select Tax behavior.
Toggle Include tax in prices to turn on inclusive pricing. Kelviq will ask you to select the specific currencies where the listed price should include tax.
If the plan has only one currency, only that currency is listed. This lets you mix billing styles on a single plan. You can select EUR to give European buyers an inclusive experience while leaving USD unchecked so North American buyers pay tax at checkout.
## Business tax ID behavior
When you sell to other businesses they are often exempt from paying sales tax or VAT. Kelviq handles this verification automatically. If a business enters a valid tax ID at checkout we apply a reverse charge and drop the tax requirement.
If you enabled tax inclusive pricing in the steps above you need to tell Kelviq how to handle the final math for these exempt B2B customers.
Open **Settings → Tax settings**.
Turn on the Business tax ID behavior toggle. When this is active Kelviq automatically reduces the checkout total by the included tax amount if the customer enters a valid business tax ID.
If you leave this disabled the checkout total remains the exact same and we attribute the extra margin directly to your account.
# Usage alerts
Source: https://docs.kelviq.com/product-catalog/usage-alerts
Configure usage thresholds and receive feature.usage_alert webhooks
Usage alerts tell your application when a customer's Meter feature crosses a threshold. Use them with any Meter feature, such as API calls, credits, tokens, or storage.
> [!NOTE]
>
> A usage alert has two parts. You configure the threshold on the plan, then receive the `feature.usage_alert` event through a webhook. Turning on the alert does not email the customer or show an in-app message by itself. Your webhook handler decides what happens next.
## How usage alerts work
1. Your application reports usage to Kelviq with `SET` or `DELTA` behavior.
2. Kelviq updates the customer's meter for the current usage period.
3. When current usage crosses a configured threshold, Kelviq creates a `feature.usage_alert` event.
4. Kelviq sends the event to webhook endpoints subscribed to that event type.
5. Your application can send an email, show an in-app warning, notify a support team, or offer an upgrade.
Usage alerts do not stop usage, change a price, or charge the customer. Use a hard limit to stop usage at zero balance, and configure usage pricing when customers should pay for additional consumption.
## Choose a threshold type
Kelviq supports percentage and absolute-unit thresholds.
| Dashboard option | API value | When it triggers | Valid values |
| - | - | - | - |
| Percentage | `PERCENTAGE` | Current usage reaches a percentage of the feature's usage limit | 1–100 |
| Balance | `BALANCE` | Current usage reaches an absolute number of feature units | Any number greater than or equal to 1 |
Suppose a plan includes 10,000 API calls each month:
* A 75% percentage threshold is crossed when current usage reaches 7,500 calls.
* A balance threshold of 7,500 is crossed at the same usage count, but it is stored as an absolute number of calls rather than a percentage.
Percentage thresholds are easier to reuse across plans with different limits. Balance thresholds are useful when the absolute number matters, such as 10,000 API calls or 1,000 AI credits.
You can add more than one threshold. For example, use 75% for an early warning and 90% for a stronger upgrade or top-up prompt.
## Configure usage alerts in the dashboard
1. Open **Product Catalog → Products** and select the product.
2. Open the plan that contains the Meter feature.
3. Edit **Usage charges** or open **Manage features & limits**.
4. Select the Meter feature and enter its usage value or pricing configuration.
5. Turn on **Usage alert**.
6. Choose **Percentage** or **Balance** as the threshold type.
7. Click **Add threshold** and enter each threshold.
8. Save the configuration. If Kelviq creates a draft version of a published plan, publish the draft before testing it.
If the Usage alert switch is disabled while managing an entitlement, make sure you selected a Meter feature and entered a value. Percentage alerts also need a finite usage limit so Kelviq can calculate the percentage used.
> [!NOTE]
>
> Regional prices inherit usage alerts from the base price. Change the base price when the same alert configuration should apply to every regional price.
## Configure usage alerts through the API
To update one plan entitlement, send a `PATCH` request to:
```text theme={null}
/api/v1/catalog/plans/{plan_identifier}/features/{feature_identifier}/
```
`feature_identifier` is the feature's identifier, such as `api-calls`, not its UUID.
```bash theme={null}
curl --request PATCH \
--url https://api.kelviq.com/api/v1/catalog/plans/pro/features/api-calls/ \
--header "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"details": {
"value": 10000,
"hasUnlimitedUsage": false,
"reset": "EVERY_MONTH",
"resetTime": "BEGINNING_OF_PERIOD",
"usageAlerts": {
"enabled": true,
"thresholds": [75, 90],
"thresholdType": "PERCENTAGE"
},
"hardLimit": false
}
}'
```
The `usageAlerts` object contains:
| Field | Type | Description |
| - | - | - |
| `enabled` | boolean | Turns alerts on or off for the entitlement |
| `thresholds` | number\[] | Percentage or unit values to watch |
| `thresholdType` | string | `PERCENTAGE` or `BALANCE` |
Updating a published plan creates a new draft version. Publish that draft before expecting the new thresholds to apply. See [Update plan entitlement](/api-reference/plan-entitlements/update-plan-entitlement) for the complete request schema.
## Create the webhook endpoint
The threshold configuration tells Kelviq when to create an alert. The webhook endpoint is how your application receives it.
1. Open **Settings → Webhooks** in the Kelviq dashboard.
2. Create an endpoint with a public HTTPS URL.
3. Subscribe the endpoint to `feature.usage_alert`.
4. Save the signing secret. Kelviq shows it once.
5. Verify every delivery before reading its data.
The webhook endpoint and usage reports must use the same environment. A production webhook does not receive alerts created from sandbox usage, and a sandbox webhook does not receive production alerts.
See the [Webhooks guide](/guides/webhooks) for signature verification, retries, delivery logs, and manual resends.
## Usage alert payload
The event identifies the customer, feature, usage limit, current usage, threshold, subscription, and usage period.
```json theme={null}
{
"id": "575a1aa4-3414-4e08-b4ad-6bfd3e96322d",
"type": "feature.usage_alert",
"created_at": "2026-05-18T18:48:59Z",
"data": {
"object": {
"id": "a1c88c9d-19cf-48cc-b194-6cc6ebb356ee",
"object": "feature_usage_alert",
"feature": {
"id": "245d745f-28ca-4856-81fe-1e1f5c6c7ebd",
"name": "API calls",
"identifier": "api-calls",
"feature_type": "METER"
},
"customer": {
"id": "d2b6c9ac-bcd5-4e59-8c7e-b6472485e112",
"name": "Geo",
"email": "geo@example.com",
"customer_id": "customer-123"
},
"usage_limit": 10000,
"current_usage": 9000,
"threshold_type": "PERCENTAGE",
"threshold_value": 90,
"period_start_time": "2026-05-01T00:00:00Z",
"period_end_time": "2026-06-01T00:00:00Z",
"subscription_id": "137e4652-5540-4a3b-9bce-fa393b028539",
"organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c"
}
}
}
```
The fields most alert handlers use are:
| Field | Use |
| - | - |
| Top-level `id` | Idempotency key for deduplicating webhook deliveries |
| `feature.identifier` | Maps the alert to a feature in your application |
| `customer.customer_id` | Maps the alert to your own user or account |
| `customer.email` | Address for a customer notification, if you choose to send one |
| `usage_limit` | Configured usage allowance |
| `current_usage` | Usage recorded when the event was created |
| `threshold_type` | Whether `threshold_value` is a percentage or absolute unit count |
| `threshold_value` | The configured threshold that was crossed |
| `period_start_time`, `period_end_time` | Usage period associated with the alert |
| `subscription_id` | Subscription that owns the entitlement |
## Handle `feature.usage_alert`
This Express example verifies the request and sends the alert to an application queue. The queue can handle email or in-app notifications outside the webhook request.
```typescript theme={null}
import express from "express";
import {
validateEvent,
WebhookVerificationError,
} from "@kelviq/node-sdk";
const app = express();
app.post(
"/webhooks/kelviq",
express.raw({ type: "application/json" }),
async (req, res) => {
try {
const event = validateEvent(
req.body,
req.headers,
process.env.KELVIQ_WEBHOOK_SECRET!,
);
if (event.type === "feature.usage_alert") {
const alert = event.data.object;
// `notificationQueue` is your own queue or background-job service.
await notificationQueue.add("usage-alert", {
eventId: event.id,
customerId: alert.customer.customer_id,
email: alert.customer.email,
featureId: alert.feature.identifier,
currentUsage: alert.current_usage,
usageLimit: alert.usage_limit,
thresholdType: alert.threshold_type,
thresholdValue: alert.threshold_value,
});
}
return res.sendStatus(202);
} catch (error) {
if (error instanceof WebhookVerificationError) {
return res.sendStatus(403);
}
return res.sendStatus(500);
}
},
);
```
Kelviq may deliver the same event more than once because of automatic retries or a manual resend. Store the top-level event `id` or `webhook-id` header before enqueueing work, and skip the event if you already processed it.
Return a `2xx` response quickly. Do not wait for an email provider or another slow service inside the webhook request.
## Test an alert in sandbox
1. Create a sandbox webhook endpoint subscribed to `feature.usage_alert`.
2. Configure a low threshold on a sandbox plan, such as 1 unit or 1%.
3. Report enough usage to cross the threshold.
4. Open **Settings → Webhooks**, select the endpoint, and inspect the delivery log.
5. Confirm the event's customer, feature, threshold, and usage period.
For example, report a usage increment with the Node SDK:
```typescript theme={null}
import { BEHAVIOUR_CHOICES, Kelviq } from "@kelviq/node-sdk";
const kelviq = new Kelviq({
accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY!,
environment: "sandbox",
});
await kelviq.reporting.reportUsage({
customerId: "customer-123",
featureId: "api-calls",
value: 2,
behaviour: BEHAVIOUR_CHOICES.DELTA,
});
```
If delivery fails, fix the endpoint and use **Resend** from the delivery log. Keep the handler idempotent because a resend can deliver the same event again.
## Troubleshooting
| Problem | What to check |
| - | - |
| The Usage alert switch is disabled | Confirm that the feature is a meter and has a configured value |
| No webhook arrives | Confirm the endpoint subscribes to `feature.usage_alert`, the plan version is published, and usage crossed a configured threshold |
| Sandbox testing produces no production delivery | Make sure usage reports, plan configuration, API key, and webhook all belong to the same environment |
| Percentage threshold does not match expectations | Compare `current_usage` with `usage_limit`; percentage thresholds measure usage against that limit |
| The handler runs twice | Deduplicate using the event `id` or `webhook-id`; retries and manual resends can duplicate a delivery |
| Customers receive no email | Kelviq emits the webhook event; your application must send the email or in-app notification |
# Usage-based pricing
Source: https://docs.kelviq.com/product-catalog/usage-based-billing
Charge customers for the actual work your product performs
Usage-based pricing charges customers for what they use: API calls, tokens, compute, or any other Meter feature.
## Set up a usage plan
The example below is a **Pro** plan: \$29 a month, 10,000 API calls included, then \$0.002 per call. [How usage limits work](/product-catalog/usage-limits) explains what happens at the limit.
**Dashboard**
Open the plan's pricing and expand **Usage charges**, then follow the steps below.
**CLI**
Define the plan in `kelviq.config.ts`. The entitlement sets the included 10,000 calls. The Pay as you go price bills calls past that at the end of each month.
```ts kelviq.config.ts theme={null}
import { feature, plan } from '@kelviq/cli/config';
export const apiCalls = feature({
identifier: 'api-calls',
name: 'API calls',
type: 'METER',
featureDetails: {
featureSubType: 'PRE_AGGREGATED_USAGE',
units: { singular: 'call', plural: 'calls' },
},
});
export const pro = plan({
identifier: 'pro',
name: 'Pro',
product: 'my-app',
entitlements: [
{ feature: 'api-calls', value: 10000, reset: 'EVERY_MONTH', hardLimit: false },
],
prices: [
{
priceType: 'PAID',
currency: 'USD',
chargeCatalogPrice: [
{
feature: null,
priceModel: 'FLAT',
paymentType: 'ADVANCE_COMMITMENT',
reset: 'NEVER',
charges: [{ chargePeriod: 'MONTHLY', priceData: { amount: 29 } }],
},
{
feature: 'api-calls',
priceModel: 'TIERED',
paymentType: 'PAY_AS_YOU_GO',
reset: 'EVERY_MONTH',
charges: [
{
chargePeriod: 'MONTHLY',
priceData: { currency: 'USD' },
tiers: [
{ upTo: 10000, unitAmount: 0, flatAmount: 0 },
{ upTo: 'inf', unitAmount: 0.002, flatAmount: 0 },
],
},
],
},
],
},
],
});
```
Preview the change, then push and publish it:
```bash theme={null}
npx kelviq push --dry-run
npx kelviq push --publish
```
See the [CLI overview](/cli/overview) and the [config reference](/cli/kelviq-config).
### 1. Select or create a Meter feature
Choose the metric you want to track from the dropdown list, such as API requests or tokens consumed. If the list is empty, [create a Meter feature](/product-catalog/create-a-feature) from **Product catalog → Features**, then return to the plan.
### 2. Choose your billing model
Select how payments are structured.
**Advance commitment**
Customers pay upfront for a baseline allotment of usage. This gives your users a predictable budget. They buy a set bucket of AI tokens or API requests at the start of the month. They consume what they paid for and avoid surprise overages.
**Pay as you go**
Customers pay for their recorded usage at the end of the monthly subscription period. You can bill for API calls, tokens, storage, compute time, or another Meter feature, either on its own or alongside a monthly base price. See [Pay as you go](/product-catalog/pay-as-you-go) for setup, usage reporting, sandbox testing, and troubleshooting.
> [!NOTE]
>
> Monthly must be the plan's only billing period. Pay as you go does not support Stair-step pricing or credit rollover.
### 3. Configure the pricing model
Kelviq supports five distinct ways to calculate the cost. Here is how the math works for each model.
***
#### Flat
The simplest way to charge for usage. Set one fixed rate for every unit consumed. No tiers, packages, or volume discounts. The total scales directly with usage.
**Best for** API products and services where the cost of serving each unit stays relatively consistent.
**Example** A translation API charging for each API call.
**Sample calculation**
| | |
| - | - |
| Rate | \$0.01 per API call |
| Usage | 15,000 API calls |
| **Total** | 15,000 × \$0.01 = **\$150** |
***
#### Package
Instead of charging for every unit individually you sell usage in predefined packages. When a customer exceeds one package they are charged for the next full package, even if they only use part of it.
**Best for** Products that want simple pricing, predictable billing increments, and a minimum charge for reserved usage.
**Example** An AI image generator selling images in packages of 100.
**Sample calculation**
| | |
| - | - |
| Package | 100 images for \$10 |
| Usage | 205 images |
| Packages required | 3 |
| **Total** | 3 × \$10 = **\$30** |
***
#### Tiered
Units are filled into pricing buckets. As usage increases it moves into cheaper brackets, while units in earlier brackets remain charged at their original rate.
**Why it's useful** Encourages higher adoption while helping you cover fixed costs for lower-volume users. Especially useful for developer platforms.
**Example** An LLM wrapper platform charging based on token usage.
**Sample calculation**
| Tier | Rate |
| - | - |
| First 1,000 tokens | \$0.10 / token |
| Next 4,000 tokens | \$0.05 / token |
A customer uses 3,500 tokens.
| | |
| - | - |
| Tier 1 | 1,000 × \$0.10 = \$100 |
| Tier 2 | 2,500 × \$0.05 = \$125 |
| **Total** | \$100 + \$125 = **\$225** |
Kelviq tracks each pricing bracket automatically.
***
#### Volume
Similar to tiered pricing, but with one major difference. Once usage reaches a specific threshold, every unit consumed during that billing cycle is charged at the new rate.
**Why it's useful** Creates a strong incentive for high-volume customers to expand their usage by rewarding them with a lower rate across their entire bill.
**Example** An API platform charging based on the number of requests processed.
**Sample calculation**
| Volume | Rate |
| - | - |
| 1 to 100,000 API calls | \$0.01 / call |
| 100,001+ API calls | \$0.007 / call (applies to all calls) |
A customer makes 120,000 API calls.
| | |
| - | - |
| **Total** | 120,000 × \$0.007 = **\$840** |
| Without the volume discount | 120,000 × \$0.01 = \$1,200 |
Kelviq automatically applies the correct rate when customers cross a volume threshold, with no custom billing logic required.
***
#### Stair-step
Customers pay a fixed fee based on the usage bracket they fall into, regardless of the exact number of units used within that bracket. There is no per-unit rate.
**Why it's useful** Combines the simplicity of subscription plans with the flexibility of usage-based scaling.
**Example** An email delivery platform charging based on monthly email volume.
**Sample calculation**
| Step | Price |
| - | - |
| Up to 10,000 emails | Flat \$50 |
| 10,001 to 50,000 emails | Flat \$150 |
A customer sends 12,000 emails. They fall into the second step and pay a flat **\$150**.
Kelviq automatically moves customers into the correct pricing step as their usage grows, with no custom billing logic required.
***
### 4. Set the pricing rules
Once you pick a pricing model you define the exact boundaries.
If you select Tiered you specify the first unit and last unit for each bucket. You can charge a per unit price and a flat fee within that same tier.
You can also set localized pricing for usage-based pricing. This lets you define different per unit rates for specific countries and currencies.
#### Regional pricing and usage controls
When you add a regional price, Kelviq carries over the base price's usage reset, usage alert, and credit rollover settings. This keeps entitlement behavior consistent while allowing the monetary price and currency to vary by region.
Update these controls on the base price when you want the same behavior across its regional prices.
### 5. Set the usage reset cadence
Configure how often the usage meter resets. Credit rollover is calculated when this reset happens.
Use **Never** for a lifetime limit, or choose a recurring reset such as every week or every month. A meter set to **Never** has no period boundary at which to roll unused credits forward.
For monthly resets, choose either the first day of the month or the customer's subscription start date.
### 6. Configure rollover and alerts
#### Credit rollover
Credit rollover lets a customer keep part of an advance commitment they did not use before the meter resets. It is available for **Advance commitment** usage prices, not **Pay as you go** prices.
To configure it:
1. In the plan editor, expand **Usage charges** and open the Meter feature.
2. Choose **Advance commitment** as the billing model.
3. Set the included **Value** and a recurring **Usage reset**.
4. Turn on **Credit rollover**.
5. Enter the **Percentage** of unused units to carry forward. The value can be from 0% to 100%.
6. Enter a **Limit** in units to cap the rollover amount.
For example, suppose a plan includes 10,000 credits each month. The customer has 2,000 credits left when the meter resets, and rollover is set to 50% with a 750-unit limit. Fifty percent of the unused balance is 1,000 credits, so the limit reduces the rollover to 750. The customer's next period starts with 10,750 credits.
> [!NOTE]
>
> The rollover limit and the usage hard limit do different jobs. The rollover limit caps the credits carried into a new period. The hard limit stops additional usage when the customer's balance reaches zero.
#### Usage alerts
Usage alerts watch a Meter feature for percentage or absolute-unit thresholds. When a customer crosses a threshold, Kelviq sends `feature.usage_alert` to your subscribed webhook endpoint. Your application can then send an email, show an in-app warning, or start an upgrade flow.
See [Usage alerts](/product-catalog/usage-alerts) for dashboard and API configuration, the webhook payload, a Node.js handler, and sandbox testing steps.
### 7. Stack multiple usage metrics
AI products rarely track just one variable. You can add as many metered usage features as you want to a single plan. Just click the Add usage pricing button at the bottom of the section to set up another metric.
## Check access and report usage
Report usage from your backend each time the feature is used, then check what's left before the next request.
```ts Node theme={null}
import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';
// Count one API call
await client.reporting.reportUsage({
customerId: 'cust_123',
featureId: 'api-calls',
value: 1,
behaviour: BEHAVIOUR_CHOICES.DELTA,
});
// Check what's left
const ent = await client.entitlements.getEntitlement({
customerId: 'cust_123',
featureId: 'api-calls',
});
if (!ent || (!ent.hasAccess && ent.hardLimit)) {
// No access, or a hard limit was reached: block or ask the customer to upgrade
}
// Past a soft limit, let the call through: it's billed as overage
```
```python Python theme={null}
# Count one API call
client.reporting.report_usage(
customerId="cust_123",
featureId="api-calls",
value=1,
behaviour="DELTA",
)
# Check what's left
ent = client.entitlements.get_entitlement(
customerId="cust_123",
featureId="api-calls",
)
if not ent or (not ent.hasAccess and ent.hardLimit):
# No access, or a hard limit was reached: block or ask the customer to upgrade
...
# Past a soft limit, let the call through: it's billed as overage
```
`remaining` is the usage left in the current period. `hasAccess` turns `false` when it reaches 0; `hardLimit` tells you whether to block. See the [Node SDK](/backend-integration/node-sdk#entitlements) and [Python SDK](/backend-integration/python-sdk) for every method.
## Model a plan with different kinds of limits
Not every plan limit should be a meter. Choose the feature type based on what the value means and how your application will use it.
| Plan capability | Feature type | Suggested configuration |
| - | - | - |
| Messages | Meter | Reset every month |
| Training runs | Meter | Reset every day |
| Active agents | Customizable | Store the plan's allowed count |
| Knowledge sources | Customizable | Store the plan's allowed count |
| WhatsApp access | Boolean | Enable on the plans that include it |
| Analytics | Boolean | Enable on the plans that include it |
| Priority support | Boolean | Enable on the plans that include it |
For metered limits, consider usage alerts at 80% and 90%. These thresholds give customers time to reduce usage or upgrade before they reach a hard limit. Rollover and overage are optional; turn them on only where they fit your pricing. See [How usage limits work](/product-catalog/usage-limits).
When a customer changes plans, Kelviq retains their existing usage counters and evaluates them against the new limits. A customer who has already consumed more than the downgraded limit may therefore become over limit as soon as the downgrade takes effect.
# How usage limits work
Source: https://docs.kelviq.com/product-catalog/usage-limits
What a limit is, when usage resets, what happens when a customer reaches the limit, and how overage is billed
A usage limit is the amount of a Meter feature a plan includes, such as 10,000 API calls a month. Your app reports usage, Kelviq counts it against the limit, and your app checks what's left before letting the customer use more.
This page follows one example: the **Pro** plan of an AI app costs \$29 a month and includes 10,000 `api-calls`, reset monthly.
## The terms
| Term | What it means |
| - | - |
| **Base fee** | The fixed price of the plan, charged each billing period whatever the usage. \$29 a month in the example. |
| **Meter feature** | A feature Kelviq counts, such as API calls, tokens, credits, or seats. |
| **Usage limit** | How much of a Meter feature the plan includes. Can be a number or unlimited. |
| **Current usage** | How much the customer has used since the last reset. |
| **Remaining** | Usage limit minus current usage. |
| **Reset** | When current usage goes back to 0. |
| **Hard limit** | Usage is blocked once the limit is reached. |
| **Soft limit** | Usage can go past the limit. Your app decides what to do, such as warn the customer or bill overage. |
| **Overage** | Usage past the included limit, billed at a per-unit rate. |
| **Customizable feature** | A number or setting per plan, such as max upload size or number of projects. Kelviq stores the value; it doesn't count usage against it. |
## How usage is counted
Your backend reports usage for a customer and a Meter feature:
* `DELTA` adds to current usage. Send it each time something is used: one API call, 1,200 tokens.
* `SET` replaces current usage. Use it for numbers you already track, such as seats in use.
In the example, after 6,500 calls the customer's entitlement looks like this:
```json theme={null}
{
"featureId": "api-calls",
"featureType": "METER",
"hasAccess": true,
"hardLimit": true,
"usageLimit": 10000,
"currentUsage": 6500,
"remaining": 3500
}
```
See [Features & limits](/product-catalog/entitlements#sdk-integration) for the SDK calls.
## When usage resets
Each Meter feature on a plan has a **usage reset**: never, or a recurring period such as every day, month, quarter, or year. For monthly resets you choose the first day of the month or the customer's subscription start date.
A reset of **Never** makes the limit a lifetime allowance. Credit packs work this way.
## What happens at the limit
For a Meter feature, `hasAccess` is `true` while `remaining` is above 0 or the limit is unlimited.
* **Hard limit:** at 10,000 calls, `hasAccess` turns `false` and additional usage is stopped until the next reset or an upgrade.
* **Soft limit:** usage keeps counting past 10,000. `hasAccess` is also `false` here, so check `hardLimit` before blocking. If the plan has an overage price, let the customer continue and the extra usage is billed.
Use [usage alerts](/product-catalog/usage-alerts) to warn customers before they get there, for example at 80% and 90%.
## Overage
To charge for usage past the included amount, add a **Pay as you go** usage price to the plan, for example a Tiered price whose first 10,000 calls are free and each call after that costs \$0.002. Kelviq bills the overage at the end of each monthly period from the usage you report. See [Pay as you go](/product-catalog/pay-as-you-go).
## Rollover
With an **Advance commitment** price, part of the unused allowance can carry into the next period. In the example, with 50% rollover capped at 750, a customer who has 2,000 calls left at the reset starts the next month with 10,750. See [credit rollover](/product-catalog/usage-based-billing#credit-rollover).
## Plan changes
When a customer upgrades or downgrades, the new plan's limits apply immediately and current usage is kept. A customer who used 6,500 calls and downgrades to a plan with 5,000 is over the limit straight away.
## Change one customer's limit
From the customer's page in the dashboard, you can override a limit for that customer or reset their usage to 0. Plan limits don't change. See [Managing customer entitlements](/product-catalog/entitlements#managing-customer-entitlements).
## If Kelviq can't be reached
The Node and Python SDKs return the last known entitlement when the API is unreachable, and queue usage reports to retry later. See [When the Entitlement API is unavailable](/product-catalog/entitlements#when-the-entitlement-api-is-unavailable).
# Create a promotion
Source: https://docs.kelviq.com/promotions/create-a-promotion
Set up purchasing power parity discounts, country overrides, and security enforcement
A promotion ties a set of discounts to one or more of your products and plans. Once created, eligible visitors will see their local discount automatically.
**1. Navigate to Promotions**
Go to **Promotions** in the sidebar, then click **+ Create promotion**.
**2. Enter a promotion name**
Give the promotion a descriptive internal name (e.g. *PPP pricing* or *Black Friday*). This is not shown to customers.
The name field is required — you cannot create a promotion without one.
**3. Select products and plans**
Choose which products and plans this promotion applies to. You can select multiple products, and for each product you can pick one or more plans.
> [!NOTE]
>
> Only **Published** plans appear in the selector. If a plan is missing, open the product in **Product catalog → Products**, then publish the plan.
At least one plan must be selected before you can create the promotion.
**4. Set up PPP group discounts**
Kelviq groups countries into economic tiers based on purchasing power. Enter a discount percentage for each group you want to target.
* Enter a value between 1–100 in the **Discount %** field for the relevant group.
* Leave the field empty (or set it to 0) for groups you do not want to discount.
You can see which countries belong to each group by expanding the group row.
**5. Add country-specific overrides (optional)**
To override the group discount for a specific country, use the **Country-specific discounts** section.
1. Search for the country by name.
2. Click the country to add it to the list.
3. Enter the exact discount percentage for that country.
Country overrides take precedence over the group discount. For example, if India is in a group with 30% off but you want to offer 40% for India specifically, add India as a country override with 40%.
**6. Configure security & enforcement**
Security toggles prevent abuse by blocking users who are masking or misrepresenting their location. All toggles are **enabled by default** — disable only if you have a specific reason to.
| Toggle | Description |
| - | - |
| **VPN protection** | Block users connecting through a VPN |
| **Tor Browser protection** | Block anonymous traffic routed via Tor |
| **Proxy server protection** | Block known proxy IP addresses |
| **Apple Relay protection** | Block users using Apple Private Relay |
| **Strict country matching** | Require the billing address country to match the discount country |
| **Crawler protection** | Block bots from accessing localized pricing |
**7. Create the promotion**
Click **Create promotion**. You will be taken to the promotion detail page where you can integrate the banner and customize its appearance.
## Editing a promotion
To update discounts, products, or security settings after creation, open the promotion and go to the **Edit rules** tab. Changes take effect immediately.
# Customize the banner
Source: https://docs.kelviq.com/promotions/customize-banner
Adjust the appearance and behavior of the Promotions UI banner to match your brand
Open a promotion and go to the **Customize banner** tab to control how the discount banner looks and behaves on your site.
## Appearance
* **Country message** — the text displayed to visitors. Use `{discount}` as a placeholder for the discount percentage and `{country}` for the visitor's country name.
Example: *"You qualify for a % discount in ."*
* **Background color** — the banner's background color. Accepts any hex value.
* **Background transparency** — opacity of the background, from 0 (fully transparent) to 100 (fully opaque).
* **Font color** — the main text color.
* **Highlight font color** — the color used for emphasized text (e.g. the discount percentage).
* **Font size** — text size in pixels.
* **Border radius** — corner rounding of the banner container, in pixels.
## Behavior
* **Placement** — choose whether the banner appears at the **top** or **bottom** of the viewport.
* **Close icon** — when enabled, a close button lets visitors dismiss the banner.
* **Unstyled mode** — when enabled, all styling controls are disabled and the banner renders without any Kelviq styles. Use this if you want to apply your own CSS from scratch.
> [!NOTE]
>
> Enabling unstyled mode will override all appearance settings above. You will need to style the banner entirely with your own CSS.
## Save changes
Click **Update banner** to apply your changes. The banner updates in real time for new visitors.
# Integrate the Promotions UI
Source: https://docs.kelviq.com/promotions/integrate
Add the Kelviq promotions banner to your app using HTML/JS, React, or the Direct API
After creating a promotion, open it and go to the **Integration** tab. You will find ready-to-use code snippets for your stack — copy the snippet, paste in your `promotionId` and Client API key, and the banner will render automatically for eligible visitors.
You will need two values:
* **`promotionId`** — the unique ID of the promotion (pre-filled in the snippet).
* **`accessToken`** — your Client API key. Find it in **Settings → API keys → Client API key**.
***
## HTML / JS
Add the script snippet to the `` of your page. It loads the SDK asynchronously, initializes it with your promotion, and renders the banner automatically. You can also call `getUpdatedPrice()`, `updatePriceElement()`, and `updatePrice()` to display discounted prices on the page.
> **[Promotions UI JS SDK](/frontend-integration/promotions-ui-js)**
>
> Installation, `init()` options, auto price update with data attributes, JS API reference, and CSS hooks.
***
## React / Next.js
Install `@kelviq/react-promotions-ui`, wrap your app in ``, and place `
ai-credits · max-projects · priority-support"] --> P["Plan: Pro
$29/month
10,000 ai-credits/month"]
P --> C["Customer: cust_123
subscribed to Pro"]
C --> B["Balance
6,500 used · 3,500 remaining"]
```
***
## Products
A product is the thing you sell. In the example, the product is **Acme AI**.
[Learn more about products →](/product-catalog/products)
***
## Plans
A plan packages a product's price and features. Acme AI has two:
| | Free | Pro |
| - | - | - |
| Price | \$0 | \$29/month |
| `ai-credits` | 500/month | 10,000/month |
| `max-projects` | 3 | 50 |
| `priority-support` | Off | On |
[Learn more about plans →](/product-catalog/plans)
***
## Features & limits
A feature is something a plan grants. You create a feature once and add it to as many plans as you like, each with its own value. In the API and SDKs, the value a plan gives a feature is called an entitlement.
There are three feature types:
| Type | What it does | In the example |
| - | - | - |
| **Boolean** | Turns something on or off | `priority-support` |
| **Meter** | Counts usage against a limit that can reset | `ai-credits` |
| **Customizable** | Stores a number or setting for each plan | `max-projects` |
Your app checks the feature, not the plan. Moving `priority-support` to the Free plan is a dashboard change, not a deploy.
[Learn more about features & limits →](/product-catalog/entitlements) · [How usage limits work →](/product-catalog/usage-limits)
***
## Digital downloads
A digital download is a file that your customers can download after purchasing.
Examples: e-books, software, music, videos.
[Learn more about digital downloads →](/product-catalog/digital-downloads)
***
## License keys
A license key is a code that your customers can use to activate a digital download.
Examples: software activation, game keys, e-books.
[Learn more about license keys →](/product-catalog/license-keys)
***
## Links
Links allow you to share important URLs with customers after they purchase your plan.
Examples: Discord servers, Slack workspaces, Notion pages, member-only dashboards.
[Learn more about links →](/product-catalog/links)
***
## Customers
A customer is a person or company that buys from you. Create a customer with your own ID, such as `cust_123`, when someone signs up in your app. When they buy Pro, Kelviq links the subscription to that customer and their `ai-credits` balance starts at 10,000.
Each time they use a credit, your backend reports it. After 6,500 credits, Kelviq shows 3,500 remaining until the monthly reset.
[Learn more about customers →](/customers-management/overview)
***
## Typical workflows
### AI and usage-based products
Billing for actual work delivered rather than just seat access.
1. Create features like AI tokens, API calls, or workflow runs
2. Create a product
3. Create plans with a base fee plus usage charges
4. Set usage limits on each plan, with a soft or hard limit
5. Integrate the SDK to report usage back to Kelviq as the AI performs work
6. Customer subscribes and pays automatically based on their actual consumption
### One-time products
Selling digital downloads, license keys, or access links:
1. Create a **product**
2. Create a **plan** with one-time pricing
3. Add **digital downloads**, **license keys**, or **links** to the plan
4. Share your checkout link or embed a pricing table
5. Customer purchases → receives their files, keys, and links
### SaaS subscriptions
Selling recurring access with feature limits:
1. Create **features** (e.g., API calls, storage, AI tokens)
2. Create a **product**
3. Create **plans** with recurring pricing (monthly/yearly)
4. Add **features & limits** to each plan (e.g., 1,000 API calls/month)
5. Integrate the **SDK** to check feature access and enforce limits
6. Customer subscribes → SDK controls what they can access
***
## Integrate with your app
To bring everything you set up in the dashboard into your app, use one of these options:
* **SDKs** ([Node](/backend-integration/node-sdk), [Python](/backend-integration/python-sdk), [React](/frontend-integration/react-sdk), [JavaScript](/frontend-integration/js-sdk)) — check feature access and enforce usage limits in code
* **[APIs](/api-reference/authentication)** — use for custom needs such as syncing usage or triggering upgrades
> [!TIP]
>
> **Webhooks are optional.** The SDKs and UI widgets read access from Kelviq directly. Use [webhooks](/guides/webhooks) when you want events in your own systems.
[See the full integration guide →](/quickstart/integrate-with-your-app)
***
## Need help?
Have questions, need help with implementation, or want a walkthrough?\
Email us at **[hi@kelviq.com](mailto:hi@kelviq.com)** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
***
# Dashboard setup
Source: https://docs.kelviq.com/quickstart/dashboard-setup
Before you can integrate Kelviq into your app, you need to configure your **products, plans, and features** in the dashboard.\
This defines your pricing and what each plan includes.
> [!TIP]
>
> Using Claude Code, Cursor, or another coding agent? [Set up with AI](/guides/set-up-with-ai) gives you a prompt that creates your products, plans, and features for you. You approve each change.
***
## Create a product
1. In the sidebar, go to **Product catalog → Products** and click **Create product**
2. Enter a product name (e.g., "Design Course", "Pro Plan", "Premium Templates")
3. Click **Save** — you'll be redirected to the product page
***
## Create a plan
From the product page:
1. Click **Create plan**
2. Enter a plan name (e.g., “Basic Plan”)
3. Click **Save** — you’ll be redirected to the plan details page
***
## Add pricing to the plan
From the plan page, click the **Price** section to configure pricing:
1. Select billing cycles: **Monthly**, **3 Months**, **6 Months**, **Yearly**, **28 Days** (when enabled), or **One Time**
2. Enter prices for each selected billing cycle
3. (Optional) Enable **Free trial** and set the trial period in days
4. Click **Save**
### Usage-based pricing
To charge for consumption, such as compute or agent runs:
1. In the Price section, add a usage charge
2. Pick the Meter feature to bill, such as AI tokens or workflow executions
3. Set the price per unit
4. Keep a flat base price too if you want hybrid pricing
See [Usage-based pricing](/product-catalog/usage-based-billing).
### Regional pricing
To offer localized prices in different currencies:
1. In the Price section, click **Add Region** under Regional Pricing
2. Select a currency (e.g., Indian Rupee, Euro)
3. Enter prices for each billing cycle in that currency
4. Click **Add Currency**
This allows you to set specific prices for different markets rather than relying on automatic currency conversion.
***
## Add digital downloads
If your plan includes downloadable content (e-books, software, course materials):
1. Click the **Digital downloads** section
2. Upload files that customers will receive after purchase
3. Files are securely delivered to customers upon successful payment
***
## Add license keys
To automatically generate unique license keys for each purchase:
1. Click the **License keys** section
2. Toggle license key generation **on**
3. Keys are automatically created and delivered to customers after purchase
You can use these keys to validate customers in your application.
***
## Add features and limits
Click the **Features & limits** section to configure feature access and usage quotas for this plan.
1. Click **Add feature**
2. A modal will open where you can create or select features
3. Configure the feature value for this plan
### Feature types
Features are created independently and can be attached to multiple plans with different values:
* **Boolean** — on or off
Examples: priority support, bonus content access, community access, custom branding
* **Customizable** — a fixed numeric limit, no usage reporting
Examples: number of downloads, max projects, storage limit (10 GB, 100 GB)
* **Meter feature** — tracked consumption, usage events sent to Kelviq, resets each billing cycle
Examples: API calls, AI generations, video renders, exports per month
Once added, features appear in the plan's feature list. You can reorder or remove them as needed.
***
## Publish the plan
Click **Publish** on the plan page. Plans stay drafts until you publish them, and customers can only buy published plans.
***
## Next steps
Your plan is now published and ready for customers.
Next, you can integrate Kelviq into your app:
* Use [checkout links](/checkout/static-checkout-url) to let customers buy your plans
* Create a customer in Kelviq when a user signs up in your app
* Use the Kelviq [SDKs](/quickstart/integrate-with-your-app) to check feature access and track usage
***
## Need help?
Have questions, need help with implementation, or want a walkthrough?\
Email us at **[hi@kelviq.com](mailto:hi@kelviq.com)** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
***
# Integrate with your app
Source: https://docs.kelviq.com/quickstart/integrate-with-your-app
After setting up your product and plans in the dashboard, you can bring them into your app using the Kelviq SDKs and UI components.
> Note: In this guide we use the **Node SDK** and **React SDK** as examples.\
> Python and JavaScript SDKs are also available, and the steps are the same.
***
## 1. Create a customer (optional)
Typically, you create a customer record when someone signs up in your app.
When they complete a purchase, Kelviq maps the transaction to the customer record automatically.
This is optional, but creating a customer in Kelviq makes it easy to track subscriptions and usage in the dashboard.
### Get your API keys
Open **Settings → API keys**. Use the **server key** in your backend and the **client key** in your frontend.
### Install the Node SDK
```bash theme={null}
npm install @kelviq/node-sdk
```
```ts theme={null}
import { Kelviq } from "@kelviq/node-sdk";
// API keys are under Settings → API keys in the dashboard
const client = new Kelviq({
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
});
// Create a customer on signup
const newCustomer = await client.customers.create({
customerId: "unique-customer-001",
email: "customer@example.com",
name: "Node SDK User",
});
```
***
## 2. Checkout links
Every published plan has a checkout link that sends customers straight to checkout.
### Get a checkout link
1. Go to **Product catalog → Products** and open your product
2. Open the plan's **⋯** menu and click **Get Link**
3. Copy the checkout URL
### Using checkout links
You can use checkout links in multiple ways:
* **Direct link** — Share the URL in emails, landing pages, or marketing campaigns
* **Button on your site** — Link your "Buy Now" or "Get Access" buttons to the checkout URL
* **With customer ID** — Append `?customer_id=unique-customer-001` to link the purchase to an existing customer
```html theme={null}
Buy Now
```
When a customer completes checkout, their subscription and features are available in Kelviq. See [Static checkout URLs](/checkout/static-checkout-url) for all link options.
***
## 3. Check feature access
Once a customer completes a purchase, their entitlements are available in the SDK.
You can check feature access in the frontend (React SDK) or backend (Node SDK).
In all examples we’ll keep using the same customer ID: `unique-customer-001`.
### React: show or hide UI based on entitlements
```tsx theme={null}
import { ShowWhenBooleanEntitled } from '@kelviq/react-sdk';
Checking…}
fallback={Dark mode not available
}
>
```
### React: read all entitlements
The React hooks need your app wrapped in [`KelviqProvider`](/frontend-integration/react-sdk#kelviqprovider).
```tsx theme={null}
import { useAllEntitlements } from '@kelviq/react-sdk';
function EntitlementsList() {
const { data: entitlements } = useAllEntitlements();
return (
{Object.values(entitlements ?? {}).map(ent => (
);
}
```
### Backend check with Node
`max-upload-size-mb` is a Customizable feature: each plan stores the largest upload it allows. `getEntitlement` returns `null` when the customer doesn't have the feature, so treat that as no access.
```ts theme={null}
const ent = await client.entitlements.getEntitlement({
customerId: "unique-customer-001",
featureId: "max-upload-size-mb",
});
const maxUploadMb = ent?.hasAccess ? ent.usageLimit ?? Infinity : 0;
if (uploadSizeMb > maxUploadMb) {
throw new Error("Upgrade required");
}
```
***
## 4. Report usage (Meter features)
For Meter features (like downloads, exports, AI generations, or API calls), send usage events from your backend.
```ts theme={null}
import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';
await client.reporting.reportUsage({
customerId: "unique-customer-001",
featureId: "downloads",
value: 1,
behaviour: BEHAVIOUR_CHOICES.DELTA,
});
```
`DELTA` adds `value` to the customer's current usage, so send it each time something is used. `SET` replaces current usage with `value`, for numbers you already count yourself, such as seats in use.
***
## Need help?
Have questions, need help with implementation, or want a walkthrough?\
Email us at **[hi@kelviq.com](mailto:hi@kelviq.com)** or [book a demo](https://cal.com/alok-vats-fkpnc9/30min).
***
# Abandoned cart recovery
Source: https://docs.kelviq.com/sales/abandoned-cart-recovery
Automatically remind customers who start checkout but do not pay
Abandoned cart recovery emails customers who start a checkout but do not complete payment. Kelviq detects the abandoned checkout, sends up to three reminder emails over three days, and expires the checkout after four. You do not need to build anything: detection, scheduling, and deduplication are handled for you.
The feature is on by default for every organization. You can turn it off in **Settings → Customer emails**.
## How a checkout becomes abandoned
Kelviq marks a checkout as abandoned when all of the following are true:
* The checkout was created at least one hour ago.
* Its status is `open` or `processing`.
* The customer has not touched it in the last 30 minutes.
Recent customer activity delays the marking, so a customer who is still filling in payment details is not emailed.
A reminder also needs somewhere to go: the customer must have an email address, taken from the linked customer record or the email entered during checkout.
## Reminder schedule
All timings are measured from when the checkout session was created.
| Event | When |
| - | - |
| Checkout marked as abandoned | After 1 hour |
| First reminder email | After 24 hours |
| Second reminder email | After 48 hours |
| Final reminder email | After 72 hours |
| Checkout expires | After 4 days |
The background jobs that send these run hourly, so an email can arrive up to an hour after its nominal time.
The reminders are sequential. The second email is only sent after the first, and the third only after the second. Each email includes a **Return to checkout** link that takes the customer back to their session, and each send is recorded so a customer is never emailed twice for the same step.
The subject lines are:
1. `You left {productName} in checkout`
2. `Still interested in {productName}?`
3. `Last reminder about your {productName} checkout`
## What happens at expiration
Four days after creation, an unpaid checkout expires:
* The checkout status becomes `expired` and its payment status becomes `canceled`.
* The recovery link in earlier emails stops working.
* No further reminders are sent.
Completed, closed, or expired checkouts never receive reminders.
## Offer a discount in the final reminder
Turn on **Offer a discount in the final reminder** in **Settings → Customer emails** and enter a percentage. The final reminder then offers that much off the checkout total. Only one discount can be active per product, so the offer isn't sent if another discount already applies to the checkout.
## Turning it off and on
Use the **Abandoned cart recovery** toggle in **Settings → Customer emails** to control the feature for your whole organization.
* Turning it off stops future reminder emails. Emails that were already sent cannot be recalled.
* Turning it back on resumes eligible reminders for checkouts that have not yet expired.
> [!NOTE]
>
> The reminder timing and email content are fixed. There is currently no option to change the schedule, resend a reminder manually, or exclude individual checkouts.
To watch recovery in action, open [Checkout sessions](/sales/checkout-sessions). An abandoned checkout stays in its `open` or `processing` state until the customer returns and pays or the session expires.
# Checkout sessions
Source: https://docs.kelviq.com/sales/checkout-sessions
Every checkout attempt, paid or not, with a timeline of what the customer did
A checkout session is created each time a customer opens a checkout link or your app creates a checkout through the API. [Orders](/sales/orders) only show purchases that went through. Checkout sessions show every attempt, so you can see where customers stop.
Open **Sales → Checkout sessions**.
Each row shows the session ID, the amount and billing period, the status, the customer's country and email (or N/A if they never entered one), the product and plan, and when the session was created. Search by name or session ID, filter by status, and change the date range above the list.
## Session statuses
| Status | What it means |
| - | - |
| **Open** | The customer has the checkout and hasn't paid yet. |
| **Processing** | The customer submitted a payment and it's being confirmed. |
| **Success** | The payment went through and an [order](/sales/orders) was created. |
| **Closed** | The session ended without a payment before it expired. |
| **Expired** | Nobody paid within four days of the session being created. |
A session that's still **Open** or **Processing** an hour after it was created, with no customer activity in the last 30 minutes, is treated as abandoned and gets [recovery emails](/sales/abandoned-cart-recovery) if the customer entered an email address.
## Session details
Click a session to open its details: the items in the checkout, the customer, the payment method used, and the session timeline.
The timeline lists what happened in the session, newest first, with the time of each event. For example:
| Event | When it's added |
| - | - |
| **Checkout started** | The customer opened the checkout. Shows whether it's a subscription or one-time purchase, and the amount. |
| **Plan selected** | The customer picked a plan or billing period. Shows the plan, period, and price. |
| **Billing address updated** | The customer entered or changed their country or address. |
| **Checkout session abandoned** | The customer left without paying. |
| **Checkout session expired** | The session reached its four-day limit without a payment. |
Payment attempts appear in the timeline too, including the decline reason when a payment fails, such as `insufficient_funds`. Use it to answer "why didn't this customer get charged?" without asking them to try again.
## Custom field responses
If the checkout collected [custom fields](/checkout/custom-fields), the customer's answers are saved on the session as `customFieldsData` in the API, and sent as `custom_fields_data` in the `checkout.completed` [webhook](/guides/webhooks#custom-field-responses).
# Create a one-time charge
Source: https://docs.kelviq.com/sales/create-a-one-time-charge
Charge a customer's saved payment method without sending them through checkout
Use the Create Charge API when an existing customer has agreed to a one-time purchase and already has a usable payment method saved in Kelviq. The payment is attempted immediately, so the customer does not need to complete another checkout session.
Common examples include selling an add-on after the original checkout or collecting a one-time setup fee from an existing customer.
> [!WARNING]
>
> Create a charge from your backend only. It requires a Server API Key, which must never be exposed in browser or mobile-app code.
## Before you start
Make sure all of the following are true:
* The customer already exists in the same Kelviq environment as your API key.
* The customer has a usable default payment method from a previous checkout or an active subscription.
* The plan has a one-time price and you know its plan identifier.
* You have the customer's unique `customerId`.
Sandbox and production are isolated. A sandbox customer or payment method cannot be charged with a production key, and the reverse is also true.
## Create the charge
Send `POST /api/v1/charges/` with the plan and customer identifiers. `chargePeriod` must be `ONE_TIME`.
```bash cURL theme={null}
curl --request POST \
--url https://sandboxapi.kelviq.com/api/v1/charges/ \
--header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"planIdentifier": "lifetime-access",
"chargePeriod": "ONE_TIME",
"customerId": "cust_789",
"currencyCode": "USD",
"features": [
{
"identifier": "seats",
"quantity": 5
}
]
}'
```
```typescript Node.js SDK theme={null}
import { Kelviq } from "@kelviq/node-sdk";
const client = new Kelviq({
accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
environment: "sandbox",
});
const charge = await client.charges.create({
planIdentifier: "lifetime-access",
chargePeriod: "ONE_TIME",
customerId: "cust_789",
currencyCode: "USD",
features: [{ identifier: "seats", quantity: 5 }],
});
console.log(charge.id, charge.status, charge.amount);
```
```python Python SDK theme={null}
import os
from kelviq_sdk import Kelviq
client = Kelviq.create_sync_client(
access_token=os.environ["KELVIQ_SANDBOX_SERVER_API_KEY"],
environment="sandbox",
)
charge = client.charges.create(
planIdentifier="lifetime-access",
chargePeriod="ONE_TIME",
customerId="cust_789",
currencyCode="USD",
features=[{"identifier": "seats", "quantity": 5}],
)
print(charge.id, charge.status, charge.amount)
```
The `features` and `currencyCode` fields are optional. Include `features` when the customer is choosing a quantity, such as five seats. If the customer already has a currency, `currencyCode` must match it.
## Handle the response
A successful request returns `201 Created` with the charge record:
```json theme={null}
{
"id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11",
"startDate": "2026-06-20",
"endDate": null,
"billingPeriodStartTime": null,
"billingPeriodEndTime": null,
"amount": "49.00",
"recurrence": "",
"currency": "USD",
"status": "active",
"product": {
"name": "Invoice Test",
"id": "88e437b8-6017-405b-9328-e0f4e140bb79",
"identifier": "invoice-test"
},
"plan": {
"name": "Lifetime Access",
"identifier": "lifetime-access"
},
"features": [],
"trialDaysRemaining": 0,
"customerId": "cust_789",
"billingType": "ONE_TIME"
}
```
Store the returned `id` with your own purchase record. You can also confirm the payment from **Sales → Orders** in the Kelviq dashboard.
## Handle failed charges
The API returns `400 Bad Request` when Kelviq cannot complete the payment. The response includes a `detail` message describing the problem.
| Cause | What to do |
| - | - |
| No default payment method | Send the customer through checkout so they can add a payment method. |
| Payment declined | Ask the customer to update their payment method, then try again with their approval. |
| Payment requires authentication | Use checkout so the customer can complete the required authentication. |
| `chargePeriod` is not `ONE_TIME` | Use `ONE_TIME`, or use the Subscriptions API for recurring billing. |
| API key and customer are in different environments | Use the matching sandbox or production key and customer. |
Do not automatically retry a `400` response. If a request times out and the outcome is unclear, check **Sales → Orders** before sending it again to avoid charging the customer twice.
## When to use checkout instead
Use a [checkout session](/checkout/checkout-configuration) when the customer needs to:
* enter a payment method for the first time;
* complete card or bank authentication;
* review and confirm the purchase in a hosted payment flow; or
* start a recurring subscription.
For every request field and response property, see [Create a charge API reference](/api-reference/charges/create-a-charge).
# Orders
Source: https://docs.kelviq.com/sales/orders
Every purchase made through your checkout, with its status, amount, and quick actions
An order is created for each purchase made through your checkout: one-time payments, the first payment of a subscription, and each renewal. Open **Sales → Orders** to see them.
Each row shows the order ID, the customer's email and name, the product, the status, when the order was paid, and the amount. Search by name or order ID, filter by status, and change the date range with the filters above the list.
## Order statuses
| Status | What it means |
| - | - |
| **Pending payment** | The order was created and the payment hasn't completed yet. |
| **Complete** | The payment succeeded. Shown as **Completed** in the list. |
| **Failed** | The payment was attempted and declined, or it errored. No money was collected. |
| **Refunded** | The full amount was refunded to the customer. |
| **Partial refund** | Part of the amount was refunded. The rest stays with you. |
| **Canceled** | The payment was canceled before it completed. Nothing was charged. |
| **Fraudulent** | The payment was identified as fraudulent. |
The same values come back as `status` from the [Orders API](/api-reference/orders/list-orders): `PENDING`, `COMPLETE`, `FAILED`, `REFUNDED`, `PARTIAL_REFUND`, `CANCELLED`, and `FRAUDULENT`.
## Quick actions
Click **⋯** at the end of a row:
* **Refund payment:** refund the full amount or part of it.
* **Resend receipt:** email the receipt to the customer again.
* **Generate invoice:** create and download the invoice for the order.
## Order details
Click the customer on any row to open the order's details.
The panel shows the order status and date, the customer's name, email, and country, and each item with its subtotal, discount, tax, and total. Click **⋯** at the top for the same actions as the list, plus **Copy signed portal link** to send the customer a link to their [customer portal](/customer-portal/overview).
The tabs below the totals show what the customer received and what happened to the order:
* **Downloads:** the files the customer can download. You can remove or hide a file for this order to revoke access.
* **License:** the license key issued for the order. You can edit the activation limit, change the expiry date, or deactivate the key.
* **Links:** the links shared with the customer after purchase.
* **Timeline:** every event on the order, newest first, such as **Order created**, **Order completed**, receipts and invoices sent, and payment results. Use it to check, for example, whether a customer was sent their receipt.
## Custom field responses
If the checkout collected [custom fields](/checkout/custom-fields), the customer's answers are saved on the order. You can see them in the order details drawer. They're returned as `customFieldsData` on the order in the API and as `custom_fields_data` in the `order.created`, `order.updated`, and `order.refunded` [webhooks](/guides/webhooks#custom-field-responses).
# Customer emails
Source: https://docs.kelviq.com/settings/customer-emails
The automated emails Kelviq sends to your customers, when each one goes out, and how to turn them off
Kelviq emails your customers at each step of a purchase or subscription: receipts, invoices, trial reminders, failed payment notices, and more. Every email is on by default. Open **Settings → Customer emails** to preview an email or turn it off.
Click the eye icon next to an email to preview it. Use its switch to stop sending it. Turning an email off stops future sends only.
## Subscriptions and lifecycle
| Email | When it's sent |
| - | - |
| **Trial expiring** | 3 days before a free trial converts to a paid subscription. |
| **Plan changed** | When the customer upgrades or downgrades. |
| **Subscription canceled** | When a subscription is canceled, to confirm it will end. |
## Payments and receipts
| Email | When it's sent |
| - | - |
| **Payment successful** | After each successful charge, one-time or recurring. |
| **Order receipt and confirmation** | Right after the customer completes checkout. |
| **Invoice email** | After each billing cycle, with the invoice. |
| **Refund processed** | When you issue a refund. |
## Dunning and recovery
These emails help you collect failed subscription payments. Keep them on unless you send your own.
| Email | When it's sent |
| - | - |
| **Upcoming invoice reminder** | Before a renewal charge. |
| **Payment failed** | As soon as a charge is declined. |
| **Payment past due** | As a follow-up when an invoice is still unpaid. |
| **Payment reminder** | For outstanding payments, before escalation. |
| **Card expired** | Before the renewal, when the customer needs to update their card. |
## Abandoned checkout recovery
Up to three reminders go to customers who start a checkout and leave without paying. One switch controls all three. You can also offer a percentage off the checkout total in the final reminder. Only one discount can be active per product, so the offer isn't sent if another discount already applies.
[Abandoned cart recovery](/sales/abandoned-cart-recovery) covers when a checkout counts as abandoned, the reminder schedule, and what happens when it expires.
## Customer account
| Email | When it's sent |
| - | - |
| **Payment method updated** | When the customer saves a new payment method in the [customer portal](/customer-portal/managing-payment-methods). |
# Members
Source: https://docs.kelviq.com/settings/members
Invite teammates to your Kelviq organization and manage their access
Members are the people who can sign in to your organization's dashboard. Kelviq doesn't charge per seat, so invite as many teammates as you need.
Open **Settings → Members** to see everyone in the organization with their role and status. The person who created the organization is its **Owner**.
## Invite a member
1. Click **Invite members**.
2. Enter their first name, last name, and email address.
3. Click **Send invite**.
Kelviq emails them an invitation to join your organization. If they don't have a Kelviq account yet, they're asked to create one. They show as **Invited** until they accept, then as **Active**.
## Manage invitations and members
Click **⋯** next to a person:
* **Resend invite** sends the invitation email again, for someone who's still **Invited**.
* **Cancel invite** withdraws an invitation that hasn't been accepted.
* **Remove** takes away a member's access to the organization immediately. This can't be undone; invite them again if you need to.
# Profile
Source: https://docs.kelviq.com/settings/profile
Your name, sign-in, time preferences, and organization name
Open **Settings → Profile** to change your own details and your organization's name.
## Your details
Change your **first name** and **last name** here. Your **primary email address** is the one you sign in with and can't be edited on this page.
If you signed up with Google, you sign in with Google by default. Click **Set password** to add a password so you can also sign in with your email address.
## Time preferences
* **Timezone:** the timezone the dashboard uses to show dates and times, such as when an order was paid.
* **Start week on:** the first day of the week in date ranges and calendars.
These change how dates are shown in the dashboard. They don't change billing dates, renewals, or anything customers see.
## Organization
**Organization name** is the name of your Kelviq organization. To change what customers see on checkout, such as your logo and colors, use [Checkout design](/checkout/checkout-design).
# Zapier
Source: https://docs.kelviq.com/settings/zapier
Connect Kelviq to Zapier to automate work across your other apps
Use Zapier to connect Kelviq to the rest of your tools without writing code, for example to send a team message or update a spreadsheet when something happens in Kelviq.
## Connect Kelviq to Zapier
1. Open **Settings → Integrations**.
2. Click **Configure in Zapier**. Zapier opens in a new tab.
3. Sign in to Zapier, or create a free account, and accept the invitation to use the Kelviq app.
4. In Zapier, create a Zap and choose **Kelviq** as the app. Pick the event you want, then connect your Kelviq account when Zapier asks.
The Kelviq app on Zapier is available by invitation, so it won't show up in Zapier's app search until you've accepted the invitation from step 3.
## Prefer code?
If you'd rather handle events in your own backend, use [webhooks](/guides/webhooks). Kelviq sends each event with its full payload to your server.