Coupons API — Validate Discount Codes Before Checkout

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.

GET /coupons/{code}/validate

Path parameters

code

string

required

The coupon code to validate (e.g., SUMMER20).

Query parameters

product_id

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

Response — 200 OK

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

code

string

The validated coupon code, echoed back from the request.

value

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.

type

string

The discount type. One of:

price — fixed amount off the order total.
percentage — percentage off the order total.

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.

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

Example request and response

curl --request GET \
  --url "https://pay.nova.money/api/v1/coupons/SUMMER20/validate?product_id=101"

{
  "code": "SUMMER20",
  "value": 20.0,
  "type": "percentage"
}

{
  "error": "Coupon is not valid for the specified product."
}

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

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

Checkout

Payments

Management

Webhooks

Coupons API — Validate Discount Codes Before Checkout

Validate a coupon

Path parameters

Query parameters

Response — 200 OK

Response — 422 Unprocessable Entity

Example request and response

​Validate a coupon

​Path parameters

​Query parameters

​Response — 200 OK

​Response — 422 Unprocessable Entity

​Example request and response

Validate a coupon

Path parameters

Query parameters

Response — 200 OK

Response — 422 Unprocessable Entity

Example request and response