Configuration & Customization - Kelviq Documentation

Checkout in Kelviq allows you to collect payments from customers. You can generate checkout links for your products, customize the checkout experience, and support multiple payment options and billing periods.

Overview

Kelviq’s checkout system:

Powers your sales - Collect payments and create customer subscriptions
Many payment methods - Cards, wallets, bank payments, and local methods
Highly configurable - Control plans, pricing, trial periods, and more
Multi-currency ready - Support customers worldwide
Easy to embed - Generate links for any product and plans, or embed checkout on your own site

Generating Checkout Links

Checkout links are generated at the product level. Each link can include one or more plans.

Quick Start

Go to Products → Select your product
Click “Get Link” → Opens the link builder
Select plans → Choose which plans to include
Configure options → Set defaults and features
Copy link → Share with customers

Link Format

A production checkout link starts with your product UUID:

https://www.kelviq.com/buy/{PRODUCT_UUID}/

Sandbox links use https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/. Copy the link from the dashboard so the environment and product UUID are correct. Add query parameters to control what the customer sees:

Parameter	What it controls	Example
`enabled`	Comma-separated plan identifiers shown at checkout	`basic,pro`
`plan_identifier`	Plan selected when checkout opens	`pro`
`charge_period`	Billing period selected when checkout opens	`MONTHLY`
`discounts_enabled`	Whether the discount-code field is available	`true`
`discount_code`	A valid discount code to apply automatically	`LAUNCH20`
`customer_id`	Customer record associated with checkout	`cust_789`
`success_url`	Where to send the customer after a successful checkout	`https://example.com/checkout/success`

For example:

https://www.kelviq.com/buy/123e4567-e89b-12d3-a456-426614174000/?enabled=basic,pro&plan_identifier=pro&charge_period=MONTHLY&discounts_enabled=true&discount_code=LAUNCH20&customer_id=cust_789&success_url=https%3A%2F%2Fexample.com%2Fcheckout%2Fsuccess

URL-encode success_url and any other parameter value that contains reserved characters. See every supported static checkout parameter and complete examples →

Multi-Plan Checkout

Include multiple plans in a single checkout to let customers choose their tier.

Configuration

Plans Configuration

Select which plans are enabled (shown to customer)
Choose a recommended plan (highlighted by default)
At least one plan stays enabled
Disabled plans don’t appear in checkout

Example: Multi-Plan Pricing

Your product has 3 plans: Free, Pro, Enterprise

Plan 1: Free
├─ Enabled: Yes
├─ Price: $0/month
└─ Show in checkout: Yes

Plan 2: Pro (Recommended)
├─ Enabled: Yes
├─ Price: $29/month
└─ Show in checkout: Yes (selected by default)

Plan 3: Enterprise
├─ Enabled: Yes
├─ Price: Custom quote
└─ Show in checkout: Yes

Generated checkout URL:

?enabled=free,pro,enterprise&plan_identifier=pro

Billing Periods & Pricing

Supported Billing Periods

Plans in Kelviq can support multiple billing periods:

Period	Duration	Use Case
Monthly	1 month	Recurring subscriptions
3 Months	3 months	Quarterly billing
6 Months	6 months	Biannual billing
Yearly	12 months	Annual billing, often with discounts
One Time	One-off payment	Digital products, courses, lifetime access

We can also add custom billing periods such as weekly, daily, or 28 days upon request. Contact hi@kelviq.com to enable these options.

Setting Default Billing Period

Configure which billing period is pre-selected for each plan:

Plan: Pro
├─ Monthly: $29/month (default for checkout)
├─ Yearly: $290/year (saves $58)
└─ Checkout pre-selects: Monthly

In your checkout link:

&charge_period=MONTHLY

Pricing by Period

Different plans can have different pricing for the same period:

Plan: Basic
├─ Monthly: $9/month
└─ Yearly: $90/year

Plan: Pro
├─ Monthly: $29/month
└─ Yearly: $290/year (17% discount vs monthly)

Plan: Enterprise
├─ Monthly: $99/month
└─ Yearly: $999/year (16% discount vs monthly)

Customers see all options and can choose their preferred period at checkout.

Free Trials

Offer free trial periods before charging customers.

Configuring Trials

Open your plan → Go to the plan’s pricing section
Enable Free Trial → Toggle the trial option
Set duration → 1-365 days (default 7 days)
Save plan

Trial Behavior

When a customer starts a trial:

Timeline:
Day 0: Customer signs up, trial begins
Days 1-30: Customer has full access, no charge
Day 30: Trial ends, first billing occurs
Day 31+: Regular subscription

Trial Configuration Example

Plan: Professional
├─ Regular price: $29/month
├─ Free trial: 30 days
├─ After trial: Full charge of $29
└─ Customer can cancel anytime during trial

Trials reduce payment friction. Customers are more likely to convert from trial to paid if they’ve experienced value.

Advanced Checkout Configuration

Success and Cancellation URLs

The success URL is optional when you link to or embed Kelviq Checkout directly. Add it only when you want Kelviq to redirect the customer to your own confirmation or onboarding page after checkout succeeds:

Customer completes purchase
    ↓
Kelviq redirects to your success page
    ↓
You can:
- Show confirmation
- Deliver files/licenses
- Set up their account
- Continue onboarding

For a static checkout link, add the URL-encoded success_url parameter when you want this redirect:

&success_url=https%3A%2F%2Fyourdomain.com%2Fcheckout-success

When creating a checkout session through the API, the successUrl field is required. You can also optionally provide a cancelUrl to redirect the customer if they cancel payment.

Checkout Session Options

POST /api/v1/checkout/ accepts options that let you tailor a checkout session without changing the underlying plan.

Field	What it does
`successUrl`	Redirects the customer after a successful checkout
`cancelUrl`	Redirects the customer if payment is cancelled
`plansEnabled`	Limits checkout to a comma-separated list of plan identifiers
`discountsEnabled`	Shows or hides discount-code entry; defaults to `true`
`discountCode`	Applies a valid discount code before checkout opens
`lockEmail`	Prevents the customer from changing the pre-filled email address
`defaultBillingCountry`	Pre-fills the billing country using a two-letter ISO country code
`currencyCode`, `customAmount`, `taxBehavior`	Sets a custom charge and its tax treatment
`metadata`	Attaches your own key-value data to the checkout session

For a complete request, webhook example, and implementation guidance, see Add metadata to checkout.

const response = await fetch("https://api.kelviq.com/api/v1/checkout/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
  },
  body: JSON.stringify({
    planIdentifier: "pro",
    chargePeriod: "MONTHLY",
    customerId: "customer-123",
    successUrl: "https://example.com/checkout/success",
    cancelUrl: "https://example.com/pricing",
    plansEnabled: "basic,pro",
    discountsEnabled: true,
    discountCode: "LAUNCH20",
    lockEmail: true,
    defaultBillingCountry: "US",
  }),
});

const { checkoutUrl } = await response.json();

Discount Code Integration

Allow customers to apply discount codes at checkout:

Customer at checkout:
Select plan and period
(Optional) Enter discount code
See adjusted price
Complete payment

Discount codes are applied automatically if the customer enters a valid code. See API and static-link examples for applying a discount code →

Tax Collection

Kelviq calculates and collects tax on every checkout, based on the customer’s location.

Business customers can enter a VAT number or other tax ID. When it’s valid, Kelviq applies the reverse charge.
Choose per plan whether listed prices include tax or tax is added at checkout. See Tax settings.

Country Restrictions

Restrict plans to specific countries:

Plan: Premium Tier
├─ Available countries: US, UK, CA, AU
├─ Restricted countries: China, Russia
└─ Checkout effect: Plan hidden for customers in restricted countries

Checkout session lifecycle

Each checkout attempt is a session with one of five statuses: Open, Processing, Success, Closed, or Expired. An unpaid session expires four days after it’s created. Checkout sessions explains each status and how to read a session’s timeline in the dashboard.

Create Checkout Sessions via API

You can programmatically create checkout sessions using the SDK:

Python
Node.js

from kelviq_sdk import Kelviq

client = Kelviq.create_sync_client(access_token="your_server_api_key")

# Create a checkout session
response = client.checkout.create_session(
    planIdentifier="plan-pro-monthly",
    chargePeriod="MONTHLY",
    customerId="cust_123",
    successUrl="https://yoursite.com/checkout/success"
)

print(f"Checkout URL: {response.checkoutUrl}")
print(f"Session ID: {response.checkoutSessionId}")

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

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

// Create a checkout session
const response = await client.checkout.createSession({
    planIdentifier: "plan-pro-monthly",
    chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
    customerId: "cust_123",
    successUrl: "https://yoursite.com/checkout/success"
});

console.log(`Checkout URL: ${response.checkoutUrl}`);
console.log(`Session ID: ${response.checkoutSessionId}`);

Checkout Flow Examples

Example 1: Simple Product

One plan, one price:

Product: My Course
├─ Plan: Full Access ($49)
└─ Billing: One-time payment

Link: ?enabled=full_access&plan_identifier=full_access&charge_period=ONE_TIME

Example 2: Tiered Plans

Multiple plans, multiple billing periods:

Product: Pro Templates
├─ Plan 1: Starter ($9/month or $90/year)
├─ Plan 2: Professional ($29/month or $290/year)
└─ Plan 3: Enterprise (Custom pricing)

Link: ?enabled=starter,pro,enterprise
       &plan_identifier=pro
       &charge_period=MONTHLY

Example 3: Free + Paid

Offer free plan with paid upgrades:

Product: Productivity App
├─ Plan 1: Free (no payment)
└─ Plan 2: Premium ($9.99/month with 30-day trial)

Link: ?enabled=free,premium
       &plan_identifier=free
       &charge_period=MONTHLY

Payment Methods

Checkout shows the payment methods available for the customer’s location and currency: cards, wallets such as Apple Pay and Google Pay, bank payments, and local methods. Cards work everywhere. See Payment methods for the full list.

Does Kelviq support UPI AutoPay?

Yes. Kelviq supports UPI AutoPay for recurring subscriptions. Eligible customers in India can authorize the recurring payment at checkout. Availability depends on support from the customer’s bank and UPI app.

Currency & Localization

Multi-Currency Support

Prices are stored per currency. When customers checkout:

Customer from EU viewing checkout:
- Product prices shown in EUR
- Customer sees "29,99 EUR"

Customer from US viewing same product:
- Product prices shown in USD
- Customer sees "$29.99"

Pricing Configuration

Set prices for each currency you support:

Plan: Pro
├─ USD: $29/month
├─ EUR: €27/month
├─ GBP: £25/month
└─ AUD: A$45/month

Price localization

A plan can have a fixed price in other currencies. Buyers get the price for where they are when checkout opens:

Plan: Professional
├─ US: $29
├─ India: ₹599
└─ Brazil: R$99

You set each amount yourself. See Location-based pricing. To give a percentage off by country instead, use Promotions.

Testing Checkout

Sandbox Testing

Test checkouts without processing real payments:

Use a test card → Use 4242 4242 4242 4242
Test various scenarios → Successful payment, declined card, etc.
Monitor test checkouts → View in your dashboard

Test Card Examples

Card	Result
4242 4242 4242 4242	Successful payment
4000 0000 0000 0002	Card declined
4000 0025 0000 3155	Requires authentication

Every other scenario, from specific decline reasons to wallets, SEPA Direct Debit and UPI, is listed in Test payments.

​Overview

​Generating Checkout Links

​Quick Start

​Link Format

​Multi-Plan Checkout

​Configuration

​Example: Multi-Plan Pricing

​Billing Periods & Pricing

​Supported Billing Periods

​Setting Default Billing Period

​Pricing by Period

​Free Trials

​Configuring Trials

​Trial Behavior

​Trial Configuration Example

​Advanced Checkout Configuration

​Success and Cancellation URLs

​Checkout Session Options

​Discount Code Integration

​Tax Collection

​Country Restrictions

​Checkout session lifecycle

​Create Checkout Sessions via API

​Checkout Flow Examples

​Example 1: Simple Product

​Example 2: Tiered Plans

​Example 3: Free + Paid

​Payment Methods

​Does Kelviq support UPI AutoPay?

​Currency & Localization

​Multi-Currency Support

​Pricing Configuration

​Price localization

​Testing Checkout

​Sandbox Testing

​Test Card Examples

Overview

Generating Checkout Links

Quick Start

Link Format

Multi-Plan Checkout

Configuration

Example: Multi-Plan Pricing

Billing Periods & Pricing

Supported Billing Periods

Setting Default Billing Period

Pricing by Period

Free Trials

Configuring Trials

Trial Behavior

Trial Configuration Example

Advanced Checkout Configuration

Success and Cancellation URLs

Checkout Session Options

Discount Code Integration

Tax Collection

Country Restrictions

Checkout session lifecycle

Create Checkout Sessions via API

Checkout Flow Examples

Example 1: Simple Product

Example 2: Tiered Plans

Example 3: Free + Paid

Payment Methods

Does Kelviq support UPI AutoPay?

Currency & Localization

Multi-Currency Support

Pricing Configuration

Price localization

Testing Checkout

Sandbox Testing

Test Card Examples