Introduction

The Kelviq API is available in two environments. Use the sandbox while building and testing your integration, then switch to production when you are ready to accept live payments.

Base URLs

Production

Use for live customers, production data, and real payments.

API	Base URL
Core API	`https://api.kelviq.com/api/v1`
Edge API	`https://edge.api.kelviq.com/api/v1`

Sandbox

Use for development, integration testing, and test payments.

API	Base URL
Core API	`https://sandboxapi.kelviq.com/api/v1`
Edge API	`https://edge.sandboxapi.kelviq.com/api/v1`

The Core API manages resources such as products, plans, customers, subscriptions, and checkout sessions. The Edge API serves latency-sensitive features such as entitlements and promotions.

Sandbox and production are isolated. API keys and data created in one environment do not work or appear in the other.

Learn how the sandbox works →

Authentication

Kelviq uses API keys. Send your Server API Key as a Bearer token when calling the API from your backend:

curl https://sandboxapi.kelviq.com/api/v1/catalog/products/ \
  --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
  --header "Accept: application/json"

Use a Client API Key for supported browser and distributed-app integrations. For example, the license activation, validation, and deactivation endpoints accept either a Client API Key or a Server API Key. Never expose a Server API Key in client-side code. Read the authentication guide →

Switching environments

For direct API calls, change the base URL and use the matching environment’s API key. Official Kelviq SDKs accept an environment option:

import { Kelviq } from "@kelviq/node-sdk";

const client = new Kelviq({
  accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
  environment: "sandbox",
});

from kelviq_sdk import Kelviq

client = Kelviq.create_sync_client(
    access_token=KELVIQ_SANDBOX_SERVER_API_KEY,
    environment="sandbox",
)

Omit environment or set it to production for live traffic.

Pagination

List endpoints that support pagination use the page and page_size query parameters.

Parameter	Type	Description
`page`	integer	Page number to return.
`page_size`	integer	Number of results to return per page. The maximum is `100`.

Pagination defaults depend on the resource:

Endpoints	Default `page_size`	Maximum `page_size`
Products, Plans, Plan Versions, and Features	`100`	`100`
All other paginated APIs	`10`	`100`

You can request fewer results by setting page_size. Values above 100 are capped at 100.

curl "https://sandboxapi.kelviq.com/api/v1/customers/?page=2&page_size=10" \
  --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY"

Paginated responses contain the total result count, links to adjacent pages, and the current page of results:

{
  "count": 250,
  "next": "https://sandboxapi.kelviq.com/api/v1/customers/?page=3&page_size=10",
  "previous": "https://sandboxapi.kelviq.com/api/v1/customers/?page=1&page_size=10",
  "results": []
}

Filtering

Search and filter parameters vary by endpoint and can be combined with pagination when supported. Use the search query parameter for free-text search and endpoint-specific query parameters for filtering.

# Search customers
curl "https://sandboxapi.kelviq.com/api/v1/customers/?search=acme&page=1&page_size=10" \
  --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY"

# Filter subscriptions by customer
curl "https://sandboxapi.kelviq.com/api/v1/subscriptions/?customer_id=customer_123" \
  --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY"

Consult the endpoint reference before adding a query parameter; unsupported parameters may be ignored or rejected.

Rate limits

To keep the API responsive for everyone, requests are rate limited per organization. The limit applies to all endpoints authenticated with a Server or Client API Key, and differs by environment:

Environment	Limit
Production	`500 requests` / minute
Sandbox	`100 requests` / minute

The limit applies to your whole organization, not to an individual API key — Server and Client API Key requests share the same quota. Sandbox and production are isolated environments, so each maintains its own limit. If you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying:

{
  "detail": "Request was throttled. Expected available in 42 seconds."
}

Honor the Retry-After header and back off before retrying. If your integration regularly approaches the limit, batch or cache requests where possible rather than polling.

Error handling

The API uses standard HTTP status codes and returns detailed error information in the response body.

HTTP Status	Name	Description
`400`	Bad Request	The request body or parameters are invalid, or a business rule prevented the operation.
`401`	Unauthorized	The API key is missing, invalid, or belongs to a different environment.
`403`	Forbidden	The credentials are valid, but the requested action is not allowed.
`404`	Not Found	The requested resource does not exist.
`405`	Method Not Allowed	The HTTP method is not supported for the requested endpoint.
`409`	Conflict	The request conflicts with an existing resource, such as a duplicate account.
`422`	Unprocessable Entity	The request is well-formed but contains invalid or unsupported values.
`428`	Precondition Required	A required account configuration, such as billing-provider authentication, is incomplete.
`429`	Too Many Requests	The rate limit has been exceeded.
`500`	Internal Server Error	Kelviq could not complete the request because of an unexpected server error.
`502`	Bad Gateway	Kelviq received an invalid response from an upstream service.
`503`	Service Unavailable	The service is temporarily unavailable.
`504`	Gateway Timeout	An upstream service did not respond in time.

Get Started

API Documentation

Base URLs

Production

Sandbox

Authentication

Switching environments

Filtering

Rate limits

Error handling

​Base URLs

​Production

​Sandbox

​Authentication

​Switching environments

​Pagination

​Filtering

​Rate limits

​Error handling

Base URLs

Production

Sandbox

Authentication

Switching environments

Pagination

Filtering

Rate limits

Error handling