Online Stamp Update API

API Version

PUT

/api/stamp/v2/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

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, onsiteToken must be sent as well.
onsiteToken string: Short-lived exchange token for on-site processing. v2 does not accept the plaintext password (onsitePwd).
When the stamp has onsiteYn = Y, send the onsiteToken returned by the Validate API as is.
Idempotency-Key is required for requests that use a token. A retry with the same key replays the original result; using the same token with a different key is rejected with 400 (error code 1228).
If a processing store was given at validation, this request must use the same store. A token issued without a store cannot be used with a store either.
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.
branchIdx integer: Issuing branch IDX. If omitted, the resource is issued by the head office; send 0 to clear it.
Available on the Business plan or higher.
storeIdx integer: Issuing store IDX. When specified, the branch that the store belongs to becomes the issuing branch. Sending a different branch results in an error.
useScope string: Usable scope. Only ALL (all stores) or BRANCH (a specific branch) is allowed. Defaults to ALL when omitted.
useBranchIdx integer: Usable branch IDX. Required only when useScope = BRANCH; always empty when ALL.

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

Issuing branch, issuing store and usable scope

The values set here are the policy stored at issuance. "Where it was issued" (issuing branch, issuing store) and "where the customer can use it" (usable scope, usable branch) are different concepts, so the parameters are separate.

Parameter	Meaning	Description
`branchIdx`	Issuing branch	If omitted, the head office issues it. Send `0` to clear it to the head office.
`storeIdx`	Issuing store	When set, the branch that the store belongs to becomes the issuing branch. Sending a different branch is rejected.
`useScope`	Usable scope	`ALL` (all stores) or `BRANCH` (a specific branch). Defaults to `ALL`.
`useBranchIdx`	Usable branch	Required only when `useScope=BRANCH`. Always empty when `ALL`.

Parameters that cannot be used — processStoreIdx (processing store) refers to the store where a validation, use, add or remove actually happened, so it cannot be used with this API. Sending it returns 400 (error code 1227).

Branch and store features are available on the Business plan or higher only.

Idempotency-Key

To retry safely when a response is lost to a network error, send a value that is unique per request in the Idempotency-Key header. You can also send it as requestId in the body; if both are sent with different values, the request is rejected. The allowed format is 8–64 characters of letters, digits and . _ : -.

Sending the same request again with the same key returns the original result without processing it again. Nothing is processed twice and webhooks are not sent again.

Use the same key only for retries of the same logical operation. Always use a new key for a different operation. Using the same key with different request content or for a different operation may be rejected with 409.

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 verification token (onsiteToken)

v2 does not accept the on-site password in plaintext (onsitePwd). Send the onsiteToken returned by the Validate API unchanged. Sending onsitePwd by itself or together with onsiteToken is rejected with 400 (error code 1227).

Idempotency-Key is required for requests that use a token. Retrying with the same Idempotency-Key returns the original processing result. Reusing the same token with a different Idempotency-Key is rejected with 400 (error code 1228).

The store used for validation must match the store where the operation is processed. If processStoreIdx was specified during validation, this request must use the same store. A token validated without a store cannot later be associated with one.

Expired, tampered, already consumed, or incorrectly bound tokens all return 1228. These causes are intentionally not distinguished because doing so could allow a third party to probe internal state using another token.

No token is required for resources that do not use on-site verification (onsiteYn = N). v1 continues to accept onsitePwd in plaintext.

This API uses the token only when an actual reward redemption transition (N → Y) occurs. Sending a token with a regular update that changes only the memo, period, or active status is rejected with 400 (error code 1227). Even if the request includes useYn = Y, the token is not consumed unless an actual N → Y transition occurs (for example, when the reward has already been redeemed).

This API does not accept a processing store parameter (processStoreIdx). When a reward is redeemed, the processing location is restored from the store bound to the token during validation, not from the request, and is recorded in the event and Webhook. This processing location is not applied to regular updates.

The same token can also be used with the Reward Redemption API (Redeem), but it can be used only once in either API. Once consumed by one API, the token is rejected by the other.

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

Stamp Update API (v2)