Install the Vivoldi app from Google Play to make it even more convenient.

Coupon Validation API (v2)

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/v2/validate?cpnNo={cpnNo} 


GET /api/coupon/v2/validate
     ?cpnNo=ZJLF0399WQBEQZJM
     &processStoreIdx=22

Request Parameters

cpnNostringrequired
Coupon number.
processStoreIdx integer
IDX of the store where this request is actually processed. When sent, the server verifies organization ownership, active status and permissions before recording it in the processing history.
The processing branch is not taken from the request; the server derives it from this store. This is different from the issuing store (storeIdx). 
{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "grpIdx": 271,
        "grpNm": "Birthday 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",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "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",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

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.
onsiteToken string
Short-lived exchange token for on-site processing.
It replaces the onsitePwd plaintext that v1 returned. It does not add an authentication factor; it keeps the long-lived password out of responses and integration logs.
It expires after 180 seconds, can be used once, and cannot be reused for another organization, resource, action or processing store. Not issued when the resource does not use on-site authentication (onsiteYn = N).
onsiteTokenExpiresIn integer
Token lifetime in seconds. Absent when no token is issued.
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
branchIdx integer
Issuing branch IDX. null for head-office issuance. This is the issuing location, not the branch where this request was processed.
branchNm string
Issuing branch name. null for head-office issuance. The name is returned even if the branch is deactivated.
storeIdx integer
Issuing store IDX. null when not specified. Different from the processing store.
storeNm string
Issuing store name. null when no issuing store is specified. The name is returned even if the store is deactivated.
issueScope string
Issuance type. Either HEAD_OFFICE (issued by head office) or BRANCH (issued by a branch). HEAD_OFFICE when branchIdx is null.
useScope string
Usable scope. Either ALL (all stores) or BRANCH (specific branch).
useBranchIdx integer
Usable branch IDX. Present only when useScope = BRANCH; null when ALL.
useBranchNm string
Usable branch name. Present only when useScope = BRANCH; null when ALL. The name is returned even if the branch is deactivated.

On-site verification token (onsiteToken)

The v2 Validate API response does not include the on-site password in plaintext (onsitePwd). Instead, it returns an onsiteToken that is valid for 180 seconds.

The goal is to minimize plaintext password exposure, not to strengthen authentication. The Validate API does not verify the password itself, so the token does not add another authentication factor. Instead, its short lifetime, single-use behavior, and context binding limit how the token can be reused.

Item Value
Lifetime 180 seconds. The validity period is also returned in onsiteTokenExpiresIn.
Uses One. After the token is consumed, only retries with the same Idempotency-Key return the original result.
Binding Organization, API key account, resource, action, and the processing store confirmed during validation
Applies to Coupon redemption, stamp reward redemption, and stamp updates with useYn = Y

No token is issued for resources that do not use on-site verification (onsiteYn = N). The v1 Validate API continues to return onsitePwd in plaintext.

Specifying the processing store

Parameter Meaning Description
processStoreIdx Processing store The store where this request is actually processed. Optional. When sent, the server verifies organization ownership, active status and permissions before recording it in the processing history.

The processing branch is not accepted from the request. The server derives and records it from the store you specify.

When the usable scope is BRANCH, the request is processed only if the branch of the verified processing store matches the usable branch, or if you authenticate with that branch's on-site password. Without either, it is rejected.

Parameters that cannot be used — branchIdx (issuing branch), storeIdx (issuing store), useScope (usable scope) and useBranchIdx (usable branch) are already-stored issuance policy and cannot be changed through this API. Sending them returns 400 (error code 1227).

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.