Pay as you go

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.

Monthly must be the plan’s only billing period. Pay as you go cannot 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, 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

Open the product and edit its plan.
In the plan’s billing periods, keep Monthly enabled and turn off every other period.
Open Usage charges and select the metered feature you want to bill for. If the list is empty, create a Meter feature from Product catalog → Features first.
For Billing model, choose Pay-as-you-go.

Selecting Pay-as-you-go as the billing model in Kelviq

Choose a pricing model and enter its rates.
Add usage alerts if you want to notify your application when usage crosses a threshold.
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 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:

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:

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:

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 metered feature on the plan
`value`	A whole-number usage quantity
`behaviour`	`DELTA` to add usage or `SET` to replace the current value

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:

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 for the request and response schema.

How billing works

The customer starts a monthly subscription.
Your backend reports usage throughout the period.
Kelviq updates the meter whenever it receives a valid report.
At the end of the subscription period, Kelviq applies the configured pricing rules to the final usage.
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 for configuration and webhook examples.

Test in sandbox

Sandbox and production have separate products, customers, subscriptions, and API keys. To test the complete flow:

Switch the dashboard to Sandbox.
Create or publish a monthly plan with a pay-as-you-go charge.
Complete a test checkout so the sandbox customer has an active subscription.
Initialize the Node SDK with environment: "sandbox", or send REST requests to https://sandboxapi.kelviq.com/api/v1.
Report a small usage value.
Open the customer’s metered entitlement and confirm that the recorded usage changed as expected.

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

Get Started

Quickstart

Product Catalog

Promotions

Checkout

Sales

Coustomers-management

Payouts

Customer-portal

Guides

Legal

Before you start

Configure the plan

Choose a pricing model

Combine a base price with usage

Report usage from your backend

Node.js

REST API

How billing works

Add alerts without stopping usage

Test in sandbox

Troubleshooting

Pay as you go shows a billing-period error

Stair-step cannot be selected

Reported usage does not appear

Usage is too high

Credit rollover is missing

​Before you start

​Configure the plan

​Choose a pricing model

​Combine a base price with usage

​Report usage from your backend

​Node.js

​REST API

​How billing works

​Add alerts without stopping usage

​Test in sandbox

​Troubleshooting

​Pay as you go shows a billing-period error

​Stair-step cannot be selected

​Reported usage does not appear

​Usage is too high

​Credit rollover is missing

Before you start

Configure the plan

Choose a pricing model

Combine a base price with usage

Report usage from your backend

Node.js

REST API

How billing works

Add alerts without stopping usage

Test in sandbox

Troubleshooting

Pay as you go shows a billing-period error

Stair-step cannot be selected

Reported usage does not appear

Usage is too high

Credit rollover is missing