Stamp Add API (v1)

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.

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/add

Request
Response

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required: Stamp IDX.

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

Use the Validation API to check stamps and maxStamps
If both values are equal, the stamp card is fully completed
Call the Update API and set useYn to Y to mark the reward as used
Call the Stamp Create API to automatically issue a reward
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.