Stamp Update API (v1)

The Stamp Update API lets you update details of stamps that have already been issued.

Beyond basic edits, you can adjust stamp counts, process reward redemption, and reset PINs, giving you full control over each user’s accumulated state.

This API is available on the Personal plan or higher.

v1 (Legacy) documentation.

For new integrations, we recommend using the latest version, v2.
v1 is intended for maintaining existing integrations and does not receive new features or improvements.

API Version

PUT

/api/stamp/v1/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsitePwd": "12345",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com"
}

Request Parameters

stampIdx integer required: Stamp IDX.
cardIdx integer: Card IDX.
The Card IDX can be found on the “Stamp Card” page in the dashboard.
stamps integer: Specifies the number of collected stamps.
Represents the total number of stamps the customer has collected. Updating this value refreshes the stamp progress and can either increase or decrease it.
When all stamps are collected (stamps = the card’s maximum stamp count), you must set useYn to Y to mark the stamp as redeemed.
resetPinYn string
Default:N
Enum: YN: Determines whether to reset the customer’s PIN code for the stamp.
Y: Resets the customer’s existing PIN. After reset, the customer must set a new PIN upon the next visit to the stamp page.
N: Keeps the current PIN unchanged.
useYn string
Default:N
Enum: YN: Specifies whether the customer has used the stamp reward.
Y: The customer has collected all stamps and redeemed a reward (e.g., free drink, discount, etc.). After redemption, the stamp becomes inactive and a new one must be issued.
N: The reward has not been used yet.
When changing from N to Y, the stored stamp count must have reached the card’s maximum, and if the stamp has an on-site password, onsitePwd must be sent as well.
onsitePwd string: Employee authentication password used for on-site stamps.
Required when changing useYn from N to Y to mark the reward as redeemed, if the stamp has onsiteYn = Y. The same validation rule as the Redeem API applies.
Not required when only changing the stamp count, or when the stamp has no on-site password.
domain string
Default:https://vvd.bz: Stamp domain.
If empty, the default domain will be used.
Available for Premium plans or higher — you can specify a custom domain registered in the Link Domain Management section.
strtYmd date: Stamp start date. Example: 2025-01-01
endYmd date: Stamp expiration date. Example: 2025-12-31
The expiration date can be set up to 5 years from today.
activeYn string
Default:Y
Enum: YN: Indicates whether the stamp is active. If disabled, the customer cannot use the stamp.
memo string: Internal memo for reference.
userId string: User ID. Used to manage the stamp recipient.
Typically, enter the website member’s login ID.
If not specified, a unique user ID is automatically generated by the system.
userNm string: User name. For internal use only.
userPhnno string: User contact number. For internal use only.
userEml string: User email address. For internal use only.
userEtc1 string: Additional internal field for management purposes.
userEtc2 string: Additional internal field for management purposes.

{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer: Response code: 0 = Success, other values = Error
message string: Response message. If the response code is not 0, an error message is returned.
result null

Numeric parameter validation

If a numeric parameter receives a non-numeric value, or a number beyond the range the server can handle, the request is rejected immediately with 400 (error code 653).

In that case no stamp data or earning history changes at all, and no event record or Webhook delivery is produced. A failed response means nothing was saved.

Behaviour change. Previously v1 kept processing the request even when this validation failed. As a result the error could be overwritten by another parameter's message, or part of the stamp data could actually be saved while the response reported an error. It now stops with 400 before processing, the same as the latest version.

Why You Need Direct Control Over Stamp Counts

When operating a stamp system, there are cases where you need to adjust stamp counts beyond automatic accumulation.

Common scenarios include correcting misissued stamps, granting bonus stamps for promotions, and manual adjustments by administrators.

By setting the stamps parameter, you can increase or decrease the current count without overwriting the existing value.
However, when the maximum number of stamps is reached (i.e., the value matches the card’s configured limit), you must also set useYn to Y to process reward redemption.

Reward Redemption and Stamp Reissue Flow

Setting useYn to Y marks the stamp as redeemed.

After redemption, a new stamp must be issued via the Stamp Creation API to restart accumulation.
This flow represents the core lifecycle of a stamp-based reward program.
Automating Redemption → New Issuance → Re-accumulation helps drive continuous repeat engagement.

On-site password for reward redemption

When changing useYn from N to Y to redeem a reward, if an on-site stamp collection password is configured for the stamp (onsiteYn = Y), you must also send onsitePwd.

This requirement is the same as for the Reward Redemption API (Redeem). It prevents a reward from being redeemed through the Update API without password verification.

To determine the password to send, check the onsitePwd value returned by the Validation API (Validate). If no on-site password is configured for the stamp, you can omit onsitePwd.

onsitePwd is not required when only changing the stamp count or updating a stamp whose reward has already been redeemed.

When to Reset a PIN

Set resetPinYn to Y to reset the user’s PIN.

Use this when a user forgets their PIN, switches devices, or when a reset is required for security reasons.

After the reset, the user will be prompted to create a new PIN when accessing the stamp page. If set to N or omitted, the existing PIN remains unchanged.

Use cases

Fixing accumulation errors: Manually correct incorrectly assigned stamp counts
Campaign rule updates: Apply updated conditions during an active campaign
User re-verification: Reset PIN to reconfigure offline authentication
Deactivation: Set stamps to inactive when a campaign ends

Things to consider

Ensure updates to stamps remain consistent with the existing accumulation history
Once marked as used (useYn), the operation should be treated as irreversible
Maintain operational logs and a detailed change history for auditing and traceability