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

Stamp Redemption API (v2)

The Stamp Redemption API marks a reward (e.g., free drink, discount) as redeemed once a customer completes all required stamps.

After redemption, the stamp cannot be used again, and a new stamp must be issued to start the next cycle.
This API is typically used in systems that provide rewards based on visit or purchase history.

This API is available on the Personal plan or higher.

PUT

/api/stamp/v2/redeem 

{
    "stampIdx": 394,
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required
Stamp IDX.
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.
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": 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.

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).

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.

Where Does Stamp Redemption Fit?

This is the final stage of the stamp system.

  • Verify that stamp accumulation is complete
  • Process reward fulfillment
  • Mark the stamp as redeemed

It is not just a state change, but the step that finalizes the campaign outcome.

Completion Point of the Stamp Lifecycle

This API represents the final step in the stamp lifecycle.

From the user’s perspective, it’s the moment they receive a reward after completing the stamps. From a developer’s perspective, it marks the end of one cycle and the start of the next.

After calling the Redemption API, issuing a new stamp immediately with the Create API helps maintain continuous user engagement.

Full Stamp Lifecycle

  1. Create → Issue a stamp to the user
  2. Add Stamp → Accumulate stamps on visits or purchases
  3. Validate → Check if all stamps are completed
  4. Redeem → Process reward redemption
  5. Create → Start a new cycle with a new stamp

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.

Post-Redemption Automation Flow

You can trigger automated workflows when a reward is marked as redeemed.

  • Call the Coupon Create API to instantly issue a reward coupon
  • Immediately create a new stamp to start the next accumulation cycle
  • Use webhooks to notify users that redemption is complete

Automating this flow enables a complete reward lifecycle—from fulfillment to re-engagement—without manual intervention.

Operational Considerations

This API is not just a feature—it is the point where business outcomes are finalized.

  • Incorrect handling can lead to duplicate rewards
  • Potential user claims or disputes
  • Increased campaign costs

Always enforce validate → redeem sequencing, server-side transactional control, and audit logging.