Create a checkout session - Kelviq Documentation

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,

THREE_MONTHS,

SIX_MONTHS

Example:

"MONTHLY"

customerId

string | null

The ID of the customer initiating the checkout. If not provided, a new customer may be created depending on server logic.

Note: Even if a unique customer ID is provided, if the email address already exists in the system, the subscription will be created for that existing email — not the new customer ID. This is to preserve the uniqueness of the email address.

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

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"