Apply a discount code at checkout

Kelviq can show a discount-code field at checkout or apply a known code before the checkout page opens. Use the first option for general promotions and the second for targeted campaigns, partner offers, or customer-specific links.

Before you start

Create the code in Product Catalog → Discounts and check that it:

is active and has not expired;
has not reached its redemption limit;
applies to the selected product and plan; and
uses the same currency as the price when it is a fixed-amount discount.

Learn how to create and restrict a discount →

Let the customer enter a code

When creating a checkout session through the API, set discountsEnabled to true. This shows the discount-code field so the customer can enter an eligible code.

{
  "planIdentifier": "pro",
  "chargePeriod": "MONTHLY",
  "customerId": "cust_789",
  "successUrl": "https://example.com/checkout/success",
  "discountsEnabled": true
}

discountsEnabled defaults to true. Set it to false only when you want to hide discount-code entry for that session.

Pre-apply a code with the Checkout API

Pass the code as discountCode in the JSON request body. Kelviq validates it while creating the checkout session. If the code is inactive, expired, or not valid for the selected plan, the request fails instead of creating a session with the wrong price.

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/checkout/ \
  --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "planIdentifier": "pro",
    "chargePeriod": "MONTHLY",
    "customerId": "cust_789",
    "successUrl": "https://example.com/checkout/success",
    "discountsEnabled": true,
    "discountCode": "LAUNCH20"
  }'

const response = await fetch("https://sandboxapi.kelviq.com/api/v1/checkout/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KELVIQ_SANDBOX_SERVER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    planIdentifier: "pro",
    chargePeriod: "MONTHLY",
    customerId: "cust_789",
    successUrl: "https://example.com/checkout/success",
    discountsEnabled: true,
    discountCode: "LAUNCH20",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { checkoutUrl } = await response.json();

import os
import requests

response = requests.post(
    "https://sandboxapi.kelviq.com/api/v1/checkout/",
    headers={
        "Authorization": f"Bearer {os.environ['KELVIQ_SANDBOX_SERVER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "planIdentifier": "pro",
        "chargePeriod": "MONTHLY",
        "customerId": "cust_789",
        "successUrl": "https://example.com/checkout/success",
        "discountsEnabled": True,
        "discountCode": "LAUNCH20",
    },
)
response.raise_for_status()

checkout_url = response.json()["checkoutUrl"]

A successful request returns the hosted checkout URL:

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

Redirect the customer to checkoutUrl. Before completing payment, confirm that checkout shows the code, adjusted price, currency, and billing period you expect.

Pre-apply a code in a static checkout link

For a static product checkout link, use the snake-case discount_code query parameter:

https://www.kelviq.com/buy/123e4567-e89b-12d3-a456-426614174000/?plan_identifier=pro&charge_period=MONTHLY&discounts_enabled=true&discount_code=LAUNCH20

Use the product UUID shown in the Kelviq dashboard. URL-encode the code if it contains spaces or reserved characters.

The names are different by design: use discountCode in an API JSON body and discount_code in a static checkout URL.

See all static checkout URL parameters →

Test the integration

Test the complete flow in sandbox before using a production code:

Create a sandbox discount and an eligible product price.
Create the checkout session with the matching sandbox API key.
Open the returned checkout URL.
Confirm the original price, discount, tax, and final total.
Complete payment with a sandbox payment method and check the resulting order.

Do not test a small live charge on your own card. Repeated self-payments can cause the card to be blocked. Use sandbox, or use a valid 100% discount when you must inspect the production checkout without collecting a real payment.

Troubleshooting

Problem	Check
Checkout creation fails	Confirm the code is active, unexpired, within its redemption limit, and valid for the selected plan.
Fixed discount is rejected	Confirm the discount currency matches the selected price currency.
The code field is missing	Set `discountsEnabled` or `discounts_enabled` to `true`, depending on how you create checkout.
The code is not pre-applied	Use `discountCode` for the API or `discount_code` for a static link.
Sandbox code is not found in production	Recreate the discount in production; the two environments do not share data.

For the complete request and response schema, see Create a checkout session API reference.

Get Started

Quickstart

Product Catalog

Promotions

Checkout

Sales

Coustomers-management

Payouts

Customer-portal

Guides

Legal

Before you start

Let the customer enter a code

Pre-apply a code with the Checkout API

Pre-apply a code in a static checkout link

Test the integration

Troubleshooting

​Before you start

​Let the customer enter a code

​Pre-apply a code with the Checkout API

​Pre-apply a code in a static checkout link

​Test the integration

​Troubleshooting

Before you start

Let the customer enter a code

Pre-apply a code with the Checkout API

Pre-apply a code in a static checkout link

Test the integration

Troubleshooting