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

Stamp Add API (v2)

The Stamp Add API increments the stamp count of an existing stamp record by one.

When a user completes a purchase, visit, or specific action, calling this API automatically adds one stamp to the record.
No additional stamps are added once the maximum defined on the stamp card is reached.

This API is available on the Personal plan or higher.

PUT

/api/stamp/v2/add 

{
    "stampIdx": 394,
    "stamps": 1,
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required
Stamp IDX.
stamps integer
Number of stamps to add (or remove). Defaults to 1 and must be greater than 0.
Amounts exceeding the card maximum or falling below zero are clamped by the server. If the actual change is 0, no history entry or webhook is created.
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.

Why This API Is Core to the Stamp System

If the Stamp Create API issues a stamp card, the Stamp Add API records real user actions.

Each time a user visits a store or completes a purchase, calling this API logs the action and enables a behavior-driven reward program without a separate points system.

Payment completion, product purchase, survey participation, and more can all be linked to stamp accumulation with a single API call.

Handling When Maximum Stamps Are Reached

If the maximum number of stamps defined on the card is reached, additional stamps will not be added.
The recommended flow is:

  1. Use the Validation API to check stamps and maxStamps
  2. If both values are equal, the stamp card is fully completed
  3. Call the Update API and set useYn to Y to mark the reward as used
  4. Call the Stamp Create API to automatically issue a reward
  5. Create a new stamp to start the next accumulation cycle

Accumulation Conditions and Constraints

Stamp accumulation is not applied automatically in all cases.

The following conditions must be satisfied:

  • Stamp is active (activeYn = Y)
  • Within the valid period (strtYmd ~ endYmd)
  • Maximum not reached (stamps < maxStamps)
  • Not already redeemed

These conditions ensure accurate accumulation aligned with your campaign rules.

Use cases

  • Visit-based rewards: Add one stamp when a user visits a store
  • Purchase rewards: Automatically add a stamp after payment is completed
  • Mission-based events: Grant stamps when specific actions are completed
  • Daily check-in: Add one stamp for each daily login

Operational Considerations

The Stamp Add API is a critical component that directly impacts campaign quality.

  • Incorrect stamp accumulation reduces trust in the campaign
  • Duplicate API calls can lead to excessive accumulation
  • It directly affects the user experience

Always use this API together with validation and server-side logic control.