Create a checkout session

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/checkout/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "plan-pro-monthly",
  "successUrl": "https://kelviq.com/checkout/success",
  "chargePeriod": "MONTHLY",
  "customerId": "cust_789",
  "features": [
    {
      "identifier": "seats",
      "quantity": 5
    }
  ],
  "ipAddress": "103.154.35.20",
  "cancelUrl": "https://kelviq.com/checkout/cancel",
  "plansEnabled": "plan-pro-monthly,plan-pro-yearly",
  "currencyCode": "USD",
  "customAmount": 2999,
  "taxBehavior": "EXCLUSIVE",
  "discountsEnabled": false,
  "discountCode": "WELCOME20",
  "lockEmail": true,
  "defaultBillingCountry": "US",
  "metadata": {
    "order_ref": "ABC-123",
    "source": "pricing_page"
  }
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/checkout/"

payload = {
    "planIdentifier": "plan-pro-monthly",
    "successUrl": "https://kelviq.com/checkout/success",
    "chargePeriod": "MONTHLY",
    "customerId": "cust_789",
    "features": [
        {
            "identifier": "seats",
            "quantity": 5
        }
    ],
    "ipAddress": "103.154.35.20",
    "cancelUrl": "https://kelviq.com/checkout/cancel",
    "plansEnabled": "plan-pro-monthly,plan-pro-yearly",
    "currencyCode": "USD",
    "customAmount": 2999,
    "taxBehavior": "EXCLUSIVE",
    "discountsEnabled": False,
    "discountCode": "WELCOME20",
    "lockEmail": True,
    "defaultBillingCountry": "US",
    "metadata": {
        "order_ref": "ABC-123",
        "source": "pricing_page"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    planIdentifier: 'plan-pro-monthly',
    successUrl: 'https://kelviq.com/checkout/success',
    chargePeriod: 'MONTHLY',
    customerId: 'cust_789',
    features: [{identifier: 'seats', quantity: 5}],
    ipAddress: '103.154.35.20',
    cancelUrl: 'https://kelviq.com/checkout/cancel',
    plansEnabled: 'plan-pro-monthly,plan-pro-yearly',
    currencyCode: 'USD',
    customAmount: 2999,
    taxBehavior: 'EXCLUSIVE',
    discountsEnabled: false,
    discountCode: 'WELCOME20',
    lockEmail: true,
    defaultBillingCountry: 'US',
    metadata: {order_ref: 'ABC-123', source: 'pricing_page'}
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/checkout/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandboxapi.kelviq.com/api/v1/checkout/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'planIdentifier' => 'plan-pro-monthly',
    'successUrl' => 'https://kelviq.com/checkout/success',
    'chargePeriod' => 'MONTHLY',
    'customerId' => 'cust_789',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 5
        ]
    ],
    'ipAddress' => '103.154.35.20',
    'cancelUrl' => 'https://kelviq.com/checkout/cancel',
    'plansEnabled' => 'plan-pro-monthly,plan-pro-yearly',
    'currencyCode' => 'USD',
    'customAmount' => 2999,
    'taxBehavior' => 'EXCLUSIVE',
    'discountsEnabled' => false,
    'discountCode' => 'WELCOME20',
    'lockEmail' => true,
    'defaultBillingCountry' => 'US',
    'metadata' => [
        'order_ref' => 'ABC-123',
        'source' => 'pricing_page'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandboxapi.kelviq.com/api/v1/checkout/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"successUrl\": \"https://kelviq.com/checkout/success\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"cancelUrl\": \"https://kelviq.com/checkout/cancel\",\n  \"plansEnabled\": \"plan-pro-monthly,plan-pro-yearly\",\n  \"currencyCode\": \"USD\",\n  \"customAmount\": 2999,\n  \"taxBehavior\": \"EXCLUSIVE\",\n  \"discountsEnabled\": false,\n  \"discountCode\": \"WELCOME20\",\n  \"lockEmail\": true,\n  \"defaultBillingCountry\": \"US\",\n  \"metadata\": {\n    \"order_ref\": \"ABC-123\",\n    \"source\": \"pricing_page\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandboxapi.kelviq.com/api/v1/checkout/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"successUrl\": \"https://kelviq.com/checkout/success\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"cancelUrl\": \"https://kelviq.com/checkout/cancel\",\n  \"plansEnabled\": \"plan-pro-monthly,plan-pro-yearly\",\n  \"currencyCode\": \"USD\",\n  \"customAmount\": 2999,\n  \"taxBehavior\": \"EXCLUSIVE\",\n  \"discountsEnabled\": false,\n  \"discountCode\": \"WELCOME20\",\n  \"lockEmail\": true,\n  \"defaultBillingCountry\": \"US\",\n  \"metadata\": {\n    \"order_ref\": \"ABC-123\",\n    \"source\": \"pricing_page\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/checkout/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"successUrl\": \"https://kelviq.com/checkout/success\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"cancelUrl\": \"https://kelviq.com/checkout/cancel\",\n  \"plansEnabled\": \"plan-pro-monthly,plan-pro-yearly\",\n  \"currencyCode\": \"USD\",\n  \"customAmount\": 2999,\n  \"taxBehavior\": \"EXCLUSIVE\",\n  \"discountsEnabled\": false,\n  \"discountCode\": \"WELCOME20\",\n  \"lockEmail\": true,\n  \"defaultBillingCountry\": \"US\",\n  \"metadata\": {\n    \"order_ref\": \"ABC-123\",\n    \"source\": \"pricing_page\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
  "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
}

POST

checkout

Create a checkout session

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/checkout/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "plan-pro-monthly",
  "successUrl": "https://kelviq.com/checkout/success",
  "chargePeriod": "MONTHLY",
  "customerId": "cust_789",
  "features": [
    {
      "identifier": "seats",
      "quantity": 5
    }
  ],
  "ipAddress": "103.154.35.20",
  "cancelUrl": "https://kelviq.com/checkout/cancel",
  "plansEnabled": "plan-pro-monthly,plan-pro-yearly",
  "currencyCode": "USD",
  "customAmount": 2999,
  "taxBehavior": "EXCLUSIVE",
  "discountsEnabled": false,
  "discountCode": "WELCOME20",
  "lockEmail": true,
  "defaultBillingCountry": "US",
  "metadata": {
    "order_ref": "ABC-123",
    "source": "pricing_page"
  }
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/checkout/"

payload = {
    "planIdentifier": "plan-pro-monthly",
    "successUrl": "https://kelviq.com/checkout/success",
    "chargePeriod": "MONTHLY",
    "customerId": "cust_789",
    "features": [
        {
            "identifier": "seats",
            "quantity": 5
        }
    ],
    "ipAddress": "103.154.35.20",
    "cancelUrl": "https://kelviq.com/checkout/cancel",
    "plansEnabled": "plan-pro-monthly,plan-pro-yearly",
    "currencyCode": "USD",
    "customAmount": 2999,
    "taxBehavior": "EXCLUSIVE",
    "discountsEnabled": False,
    "discountCode": "WELCOME20",
    "lockEmail": True,
    "defaultBillingCountry": "US",
    "metadata": {
        "order_ref": "ABC-123",
        "source": "pricing_page"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    planIdentifier: 'plan-pro-monthly',
    successUrl: 'https://kelviq.com/checkout/success',
    chargePeriod: 'MONTHLY',
    customerId: 'cust_789',
    features: [{identifier: 'seats', quantity: 5}],
    ipAddress: '103.154.35.20',
    cancelUrl: 'https://kelviq.com/checkout/cancel',
    plansEnabled: 'plan-pro-monthly,plan-pro-yearly',
    currencyCode: 'USD',
    customAmount: 2999,
    taxBehavior: 'EXCLUSIVE',
    discountsEnabled: false,
    discountCode: 'WELCOME20',
    lockEmail: true,
    defaultBillingCountry: 'US',
    metadata: {order_ref: 'ABC-123', source: 'pricing_page'}
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/checkout/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandboxapi.kelviq.com/api/v1/checkout/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'planIdentifier' => 'plan-pro-monthly',
    'successUrl' => 'https://kelviq.com/checkout/success',
    'chargePeriod' => 'MONTHLY',
    'customerId' => 'cust_789',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 5
        ]
    ],
    'ipAddress' => '103.154.35.20',
    'cancelUrl' => 'https://kelviq.com/checkout/cancel',
    'plansEnabled' => 'plan-pro-monthly,plan-pro-yearly',
    'currencyCode' => 'USD',
    'customAmount' => 2999,
    'taxBehavior' => 'EXCLUSIVE',
    'discountsEnabled' => false,
    'discountCode' => 'WELCOME20',
    'lockEmail' => true,
    'defaultBillingCountry' => 'US',
    'metadata' => [
        'order_ref' => 'ABC-123',
        'source' => 'pricing_page'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandboxapi.kelviq.com/api/v1/checkout/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"successUrl\": \"https://kelviq.com/checkout/success\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"cancelUrl\": \"https://kelviq.com/checkout/cancel\",\n  \"plansEnabled\": \"plan-pro-monthly,plan-pro-yearly\",\n  \"currencyCode\": \"USD\",\n  \"customAmount\": 2999,\n  \"taxBehavior\": \"EXCLUSIVE\",\n  \"discountsEnabled\": false,\n  \"discountCode\": \"WELCOME20\",\n  \"lockEmail\": true,\n  \"defaultBillingCountry\": \"US\",\n  \"metadata\": {\n    \"order_ref\": \"ABC-123\",\n    \"source\": \"pricing_page\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandboxapi.kelviq.com/api/v1/checkout/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"successUrl\": \"https://kelviq.com/checkout/success\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"cancelUrl\": \"https://kelviq.com/checkout/cancel\",\n  \"plansEnabled\": \"plan-pro-monthly,plan-pro-yearly\",\n  \"currencyCode\": \"USD\",\n  \"customAmount\": 2999,\n  \"taxBehavior\": \"EXCLUSIVE\",\n  \"discountsEnabled\": false,\n  \"discountCode\": \"WELCOME20\",\n  \"lockEmail\": true,\n  \"defaultBillingCountry\": \"US\",\n  \"metadata\": {\n    \"order_ref\": \"ABC-123\",\n    \"source\": \"pricing_page\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/checkout/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"successUrl\": \"https://kelviq.com/checkout/success\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"cancelUrl\": \"https://kelviq.com/checkout/cancel\",\n  \"plansEnabled\": \"plan-pro-monthly,plan-pro-yearly\",\n  \"currencyCode\": \"USD\",\n  \"customAmount\": 2999,\n  \"taxBehavior\": \"EXCLUSIVE\",\n  \"discountsEnabled\": false,\n  \"discountCode\": \"WELCOME20\",\n  \"lockEmail\": true,\n  \"defaultBillingCountry\": \"US\",\n  \"metadata\": {\n    \"order_ref\": \"ABC-123\",\n    \"source\": \"pricing_page\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
  "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
}

Click the base URL in the API playground and select the Sandbox host for test data or the Production host for live data. Use credentials from the same environment.

Authorizations

Authorization

string

header

required

The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer YOUR_API_KEY'

Body

application/json

planIdentifier

string

required

The identifier of the specific plan the customer is checking out with.

Example:

"plan-pro-monthly"

successUrl

string<url>

required

The URL to which the user will be redirected after a successful checkout.

Example:

"https://kelviq.com/checkout/success"

chargePeriod

enum<string>

required

The billing cycle for the subscription.

Available options:

ONE_TIME,

MONTHLY,

YEARLY,

WEEKLY,

DAILY,

TWENTY_EIGHT_DAYS,

THREE_MONTHS,

SIX_MONTHS

Example:

"MONTHLY"

customerId

string | null

The customerId of the customer initiating the checkout. If omitted, Kelviq creates a new customer and generates a unique customerId. Multiple customer records can share the same email address, but every customerId must be unique.

Example:

"cust_789"

features

object[] | null

A list of features and their desired quantities. SDK documentation notes this as 'Required', but usage may vary based on examples.

Show child attributes

Example:

[{ "identifier": "seats", "quantity": 5 }]

ipAddress

string | null

The IP Address of the customer, used for location-based pricing.

Example:

"103.154.35.20"

cancelUrl

string<url> | null

The URL to which the user will be redirected if the payment is cancelled.

Example:

"https://kelviq.com/checkout/cancel"

plansEnabled

string | null

A comma-separated list of plan identifiers to display on the checkout page.

Example:

"plan-pro-monthly,plan-pro-yearly"

currencyCode

string | null

The currency code for the checkout session (e.g. 'USD'). Required when customAmount is provided with a server API key.

Example:

"USD"

customAmount

number | null

A custom amount to charge for this checkout session. When provided, taxBehavior is required. When using a server API key, currencyCode is also required.

Example:

2999

taxBehavior

enum<string> | null

Specifies how taxes are applied to the custom amount. Required when customAmount is provided. INCLUSIVE means tax is included in the amount; EXCLUSIVE means tax is added on top.

Available options:

INCLUSIVE,

EXCLUSIVE

Example:

"EXCLUSIVE"

discountsEnabled

boolean | null

Whether discount/coupon code entry is shown on the checkout page. Defaults to true.

Example:

false

discountCode

string | null

A discount/coupon code to pre-apply to the checkout session. The code is applied only if it is active, unexpired, and valid for the selected plan; otherwise the request fails with an error.

Example:

"WELCOME20"

lockEmail

boolean | null

When true, the email field on the checkout page is pre-filled and locked so the customer cannot change it. Defaults to false.

Example:

true

defaultBillingCountry

string | null

ISO 3166-1 alpha-2 country code used to pre-fill the billing address country on the checkout page.

Example:

"US"

metadata

object | null

Arbitrary key-value pairs to attach to the checkout session. The keys are preserved verbatim and the object is returned unchanged on the checkout.completed webhook payload's metadata field.

Example:

{
  "order_ref": "ABC-123",
  "source": "pricing_page"
}

Response

201 - application/json

Checkout Session Created

checkoutUrl

string<url>

The URL that the customer should be redirected to complete the payment.

Example:

"https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/"

checkoutSessionId

string

The unique ID for the created checkout session.

Example:

"cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"

Update a customer

List checkout sessions

Get Started

API Documentation

Create a checkout session

Authorizations

Body

Response