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

# Coupons API — Validate Discount Codes Before Checkout

> Validate a discount code against one or more products before checkout. Returns the coupon's discount type and value, or a 422 if the coupon is invalid.

The Coupons API lets you validate a discount code before presenting it to the customer at checkout. Calling this endpoint before submitting the payment request gives you instant feedback on whether the coupon applies to the selected product and lets you display the discounted price in real time. All endpoints are relative to the base URL `https://pay.nova.money/api/v1`.

***

## Validate a coupon

Check whether a coupon code is valid and retrieve its discount type and value for one or more products.

```text theme={null}
GET /coupons/{code}/validate
```

### Path parameters

<ParamField path="code" type="string" required>
  The coupon code to validate (e.g., `SUMMER20`).
</ParamField>

### Query parameters

<ParamField query="product_id" type="string">
  The product ID (or comma-separated list of product IDs) to validate the coupon against. When multiple IDs are supplied, the coupon must apply to all of them.

  Examples:

  * Single product: `?product_id=101`
  * Multiple products: `?product_id=101,102,103`
</ParamField>

### Response — 200 OK

The coupon is valid and applies to the given product(s).

<ResponseField name="code" type="string">
  The validated coupon code, echoed back from the request.
</ResponseField>

<ResponseField name="value" type="float">
  The discount amount. Interpretation depends on `type`:

  * `price` — a fixed monetary amount to subtract from the order total.
  * `percentage` — a percentage to deduct from the order total.
</ResponseField>

<ResponseField name="type" type="string">
  The discount type. One of:

  * `price` — fixed amount off the order total.
  * `percentage` — percentage off the order total.
</ResponseField>

### Response — 422 Unprocessable Entity

Returned when the coupon code does not exist, has expired, has been exhausted, or does not apply to the specified product(s). The response body contains an error message describing the reason.

<Warning>
  Always handle the 422 response in your checkout UI. Display a clear message to the customer when their coupon is invalid or not applicable to their selected product(s).
</Warning>

### Example request and response

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://pay.nova.money/api/v1/coupons/SUMMER20/validate?product_id=101"
  ```
</CodeGroup>

<CodeGroup>
  ```json 200 OK theme={null}
  {
    "code": "SUMMER20",
    "value": 20.0,
    "type": "percentage"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "error": "Coupon is not valid for the specified product."
  }
  ```
</CodeGroup>

<Note>
  Once you have validated a coupon, you can pass it in two places:

  1. **`GET /payment_plans`** — include the coupon code as a query parameter to receive plan amounts with the discount already applied, so you can display the correct price to the customer before they confirm.
  2. **Payment request body** — include the coupon code in the `coupon` field when calling `POST /orders` or `POST /customers` (with `create_deal: true`) to have the discount applied to the created order.
</Note>


## Related topics

- [How to Validate and Apply Discount Coupons in Nova.Pay](/guides/coupons.md)
- [Build a Custom Nova.Pay Checkout with AI](/guides/ai-checkout-skill.md)
- [Create and Process Your First Payment with Nova.Pay](/guides/create-payment.md)
- [Payment Plans API — List and Retrieve Installment Options](/api-reference/payment-plans.md)
- [Nova.Pay API Errors: Status Codes and Response Handling](/errors.md)