Configuration & Customization

Configure and customize checkout experiences for your customers

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
• Integrates with Stripe - Uses Stripe as the payment processor
• 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

Generating Checkout Links

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

Quick Start

1. Go to Products → Select your product
2. Click “Generate Checkout Link” → Opens the link builder
3. Select plans → Choose which plans to include
4. Configure options → Set defaults and features
5. 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. The old product identifier is not used in checkout URLs.

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)
• Cannot disable all plans
• 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 [e-mail] 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 (2.5% 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

1. Open your plan → Go to the plan’s pricing section
2. Enable Free Trial → Toggle the trial option
3. Set duration → 1-365 days (default 7 days)
4. 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:
1. Select plan and period
2. (Optional) Enter discount code
3. See adjusted price
4. 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 can collect and handle taxes:

Tax ID Collection:

• Customers can enter their tax ID (VAT number, EIN, etc.)
• Used to determine applicable taxes
• Required for some jurisdictions

Configuration:

• Enable/disable tax collection per product
• Taxes are calculated based on customer location and tax ID

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

Checkout sessions track the state of each checkout attempt:

Session States

open
├─ Customer is in checkout
├─ No payment yet
└─ Session expires after 24 hours

↓

success
├─ Payment completed
├─ Customer created (if new)
├─ Subscription created
└─ Files and licenses delivered

OR

closed
├─ Customer abandoned checkout
├─ No payment processed
├─ Customer can restart
└─ Session expired

Monitoring Checkouts

View checkout sessions in the dashboard:

1. Go to Sales → Checkout sessions
2. View sessions → See all active and completed checkouts
3. Filter by status → Open, Success, Closed, Expired
4. Conversion metrics → Track conversion rates

Create Checkout Sessions via API

You can programmatically create checkout sessions using the SDK:

Python

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

Node.js

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

Kelviq uses Stripe as its payment processor. Stripe supports:

• Credit/Debit Cards - Visa, Mastercard, American Express, Discover
• Digital Wallets - Apple Pay, Google Pay
• UPI and UPI AutoPay - UPI payments and recurring subscription mandates for eligible customers in India
• Bank Transfers - ACH, SEPA, etc. (regional)
• Local Methods - iDEAL, Bancontact, Giropay, EPS (regional)

Customers select their preferred payment method at checkout.

Payment method availability depends on customer location and Stripe’s local support. Cards are universally supported.

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

Regional Pricing

Offer different prices based on customer location (PPP - Purchasing Power Parity):

Plan: Professional ($29 in US)
├─ India: ₹599 (auto-adjusted for PPP)
├─ Brazil: R$99
└─ US: $29

Testing Checkout

Sandbox Testing

Test checkouts without processing real payments:

1. Use Stripe test cards → Use 4242 4242 4242 4242
2. Test various scenarios → Successful payment, declined card, etc.
3. 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