Introduction

Base URLs, environments, and authentication for the Kelviq API

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 integrations. 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:

Node.js

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.

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