Apply a discount code at checkout

Let customers enter a discount code or pre-apply one to a Kelviq 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

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:

1. Create a sandbox discount and an eligible product price.
2. Create the checkout session with the matching sandbox API key.
3. Open the returned checkout URL.
4. Confirm the original price, discount, tax, and final total.
5. 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.