> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kelviq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 →](/product-catalog/discounts)

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

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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"]
  ```
</CodeGroup>

A successful request returns the hosted checkout URL:

```json theme={null}
{
  "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:

```text theme={null}
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.

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

[See all static checkout URL parameters →](/checkout/static-checkout-url)

## 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](/api-reference/checkout/create-a-checkout-session).