Stamp Validation API

The Stamp Validation API checks whether a stamp is in a valid state before adding or removing stamps, or processing reward redemption.

It verifies the stamp IDX, validity period, activation status, and whether the reward has already been redeemed in a single request.

In addition to validation, it returns the current accumulation status and card details, allowing you to build a user-facing stamp view.

This API is available on the Personal plan or higher.

GET

/api/stamp/v1/validate?stampIdx={stampIdx} 


GET /api/stamp/v1/validate
     ?stampIdx=274

Request Parameters

stampIdx integer required
Stamp IDX. 
{
    "code": 0,
    "message": "",
    "result": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsitePwd": "123456",
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "payloadVersion": "v1"
    }
}

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
If the verification succeeds, the response will include the stamp information.
If the verification fails, the response value will be null, and the error message will indicate the cause.
stampIdx integer
Stamp IDX.
domain string
Stamp domain.
cardIdx integer
Card IDX.
cardNm string
Card name.
cardTtl string
Card title.
stamps integer
Number of collected stamps so far.
maxStamps integer
Maximum number of stamps for the card.
stampUrl string
URL of the stamp page.
url string
The URL to which the user is redirected when clicking the button on the stamp page.
strtYmd date
Stamp validity start date.
endYmd date
Stamp expiration date.
onsiteYn string
Enum:
YN
Indicates whether on-site accumulation is enabled. If the value is Y, store staff can add stamps at the location.
onsitePwd string
On-site accumulation password. Required when on-site accumulation (Y) is enabled for using the stamp reward API.
memo string
Internal memo for reference.
activeYn string
Enum:
YN
Indicates whether the stamp is active. If deactivated, customers cannot use the stamp.
userId string
User ID. Used to manage the recipient of the stamp.
Typically, this corresponds to the website member’s login ID.
If not set, the system automatically generates a user ID.
userNm string
User name. For internal management.
userPhnno string
User phone number. For internal management.
userEml string
User email address. For internal management.
userEtc1 string
Additional internal management field.
userEtc2 string
Additional internal management field.
stampImgUrl string
URL of the stamp image.
regYmdt datetime
Stamp creation date. Example: 2025-07-21 11:50:20

What Is the Role of Stamp Validation?

The Stamp Validation API goes beyond a simple validity check.
It determines the next action based on the current accumulation state.

  • Check if additional stamps can be issued
  • Verify whether reward conditions are met
  • Confirm campaign participation status
  • Retrieve per-user progress

In short, the Stamp Validation API is the core endpoint for reading campaign progress.

What You Can Determine from the Validation Result

The response (result) contains all data required to evaluate stamp progress.

With this data, you can:

  • Compare current count (stamps) with maximum (maxStamps)
  • Determine whether further accumulation is allowed
  • Check if reward conditions are satisfied
  • Verify stamp status (activeYn)
  • Evaluate availability context (onsiteYn)
  • Apply personalization based on user data

Key point: “Validation API = State retrieval + Input for decision logic”

How to Use the Response Data

The validation API response is used directly within application logic.

Examples:

  • Render progress UI: Display real-time progress on the frontend
  • Control actions: Enable or disable accumulation buttons based on state
  • Trigger rewards: Show rewards when milestones are reached
  • Handle user states: Branch logic per user progress and campaign status

In short, this API is the core data source that connects UI and business logic.

Difference from Coupon Validation API

Both APIs return validation results with detailed data, but the nature of the data differs.

Coupon validation returns transaction-focused data such as discount type, discount value, and usage limits.
Stamp validation returns progression data such as current stamps (stamps), maximum stamps (maxStamps), card name, title, and stamp image URL.

The Coupon Validation API is used to calculate “how much discount applies now”,
while the Stamp Validation API is used to show “how much has been collected and how much remains”.

Operational Importance

The Stamp Validation API is at the core of the event flow.

  • Prevents incorrect stamp accumulation
  • Blocks actions when conditions are not met
  • Improves user experience
  • Ensures stability of event logic

Skipping validation can lead to data inconsistencies and event errors.

Things to consider

  • State may change between validation and actual accumulation
  • Call the accumulation API immediately after validation to minimize risk
  • Avoid relying solely on client-side validation for business logic
  • In high-traffic environments, optimize API calls and implement retry strategies on failure