Coupon Validation API

The Vivoldi Coupon Validation API lets you verify whether a coupon is valid before processing redemption.

In addition to availability, it returns discount details, usage conditions, and user data, enabling flexible business logic.

This API is available on the Personal plan or higher.

GET

/api/coupon/v1/validate?cpnNo={cpnNo} 


GET /api/coupon/v1/validate
     ?cpnNo=ZJLF0399WQBEQZJM

Request Parameters

cpnNostringrequired
Coupon number. 
{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "discTypeIdx": 457,
        "discCurrency": "USD",
        "formatDiscCurrency": "$60",
        "disc": 60.0,
        "strtYmd": "2025-01-01",
        "endYmd": "2025-12-31",
        "useLimit": 1,
        "imgUrl": "https://file.vivoldi.com/coupon/2024/11/08/lmTFkqLQdCzeBuPdONKG.webp",
        "onsiteYn": "Y",
        "onsitePwd": "12345",
        "memo": "60% off cake with coupon at the venue",
        "url": "",
        "userId": "user08",
        "userNm": "Emily",
        "userPhnno": "202-555-0173",
        "userEml": "test@gmail.com",
        "userEtc1": "",
        "userEtc2": "",
        "useCnt": 0,
        "regYmdt": "2024-11-17 17:29:25"
    }
}

Response Parameters

codeinteger
Response code: 0 = Success, any other value = Error
messagestring
Response message. If the response code is not 0, an error-related message is returned.
resultobject
Verification Success: The response returns the coupon information.
Verification Failure: The response is null, and the error message provides details.
cpnNostring
Coupon number.
domain string
Coupon domain.
nmstring
Coupon name.
discTypeIdxinteger
Discount type. (457: Percentage discount %, 458: Fixed amount discount)
discdouble
For percentage (457): range 1–100%. For fixed amount (458): enter amount.
discCurrencystring
Currency unit. Required when using fixed amount discount (discTypeIdx:458).
formatDiscCurrencystring
Currency symbol.
strtYmddate
Coupon valid start date.
endYmddate
Coupon expiration date.
useLimitinteger
Coupon usage limit. (0: Unlimited, 1–5: Limited number of uses)
imgUrlstring
Coupon image URL.
onsiteYnstring
Onsite coupon option. Determines whether the “Use Coupon” button is displayed on the coupon page.
Required when coupons are redeemed in offline stores.
onsitePwd string
현장쿠폰 비밀번호.
현장쿠폰 여부(Y)일 경우, 쿠폰 사용 API 호출 시 반드시 필요합니다.
memostring
Internal reference note.
urlstring
If a URL is entered, a “Go to Use Coupon” button will be shown on the coupon page.
Clicking the button or the coupon image redirects to the URL.
userIdstring
Used to manage the recipient of the coupon.
Required if coupon usage limit is set to 2–5.
Typically enter the website member’s login ID or English name.
userNmstring
Coupon user name. For internal management.
userPhnnostring
Coupon user contact number. For internal management.
userEmlstring
Coupon user email. For internal management.
userEtc1string
Additional internal field.
userEtc2string
Additional internal field.
useCntinteger
Number of times the coupon has been used.
regYmdtdatetime
Coupon creation date. Example: 2025-07-21 11:50:20

What Can You Determine from the Validation Result?

This API goes beyond a simple “valid / invalid” check.
It is designed to let developers build custom decision logic using detailed coupon data.

Using the response (result), you can determine:

  • Whether a discount can be applied and calculate the discount amount
  • Whether the coupon is restricted to specific users (userId, userEml)
  • Whether usage limits have been exceeded (useCnt, useLimit)
  • Whether the coupon is expired or not yet active (strtYmd, endYmd)
  • Whether specific conditions (online/offline, etc.) are met (onsiteYn)
  • The destination URL after applying the coupon (url)

In short, this is not just a status check,
but a data-driven API that enables flexible application-level logic.

Validation Method

Validation is performed based on the coupon code (cpNo) across multiple criteria.

  • Existence
  • Validity period
  • Usage limits
  • User eligibility
  • Applicable environment

The result is returned as structured data rather than a simple Boolean value.

How to Use the Response Data

The result object contains all essential coupon data.

Developers can use this data to:

  • Calculate and display discounts in real time on the frontend
  • Restrict coupon usage to specific users
  • Apply conditional logic based on the payment amount
  • Show UI messages based on coupon status (expired, redeemed, etc.)

Use cases

  • Pre-check before checkout: When a user enters a coupon code, validate it first and apply the discount only if it is valid
  • User messaging: Display appropriate messages based on validation results (e.g., expired or already redeemed)
  • Amount-based discount calculation: Use discount data (disc, discType) to calculate the final payable amount

Even after deletion, the same coupon code can be reused to create a new coupon if needed.

Things to consider

  • The validation result reflects the state at the time of the request and may change before redemption.
  • Always implement the flow: validate → redeem.
  • Relying solely on client-side validation results is insecure.
  • Re-validate discount calculations on the server to ensure accuracy and security.