Coupon Redeem API for Online Coupons

API Version

PUT

/api/coupon/v2/redeem

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233",
    "processStoreIdx": 22
}

Request Parameters

cpnNo string required: Coupon number.
onsiteToken string: Short-lived exchange token for on-site processing. v2 does not accept the plaintext password (onsitePwd).
When the coupon 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.
userId string: User ID. An identifier for the coupon issuer/user.
Must be provided if the coupon usage limit is set to 2–5.
memo string: Internal reference note. Can be used to record user IP, coupon usage location, or other details.
If coupon usage is unlimited, you can use this field instead of userId to distinguish users.
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

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.

How to Use with the Validation API

Since the Coupon Redeem API changes the coupon state, it is recommended to verify validity first using the Validation API before calling it.

By confirming the coupon is valid in advance, you can avoid unnecessary processing for expired or already redeemed coupons.

The standard flow is: validate → redeem.

When to Use This API

Use this API when you need to apply a coupon after validation.

Mark a coupon as redeemed after successful payment
Record discount usage when an order is confirmed
Handle in-store or offline coupon redemption
Update status to prevent duplicate usage

In short, this is the final step where the coupon is actually consumed.

Coupon Redemption Flow

The coupon is marked as redeemed based on the coupon code (cpnNo).

The usage count is reduced immediately upon redemption
The coupon is transitioned to a non-reusable state
Redemption is recorded based on user information (userId)
Additional logs can be stored using the memo field

This is not just a status update, but a core transaction tied to payment processing.

User Identification and Memo Usage

The userId identifies the user who redeemed the coupon.

If the coupon allows 2–5 uses, this value is required and prevents duplicate usage by the same user.

The memo field can store internal reference data such as user IP, usage location, or request source.
When usage is unlimited, memo can also be used instead of userId to distinguish users.

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.

Use cases

E-commerce checkout integration: Call the Redeem API when payment is completed to automatically apply the coupon and record discount details
In-store processing: Staff scan a QR code, retrieve the coupon code, and redeem it instantly via API
Usage tracking: Store user IP and request source in memo to analyze abuse or abnormal usage patterns
Multi-use coupon control: Use userId to prevent the same user from exceeding the allowed usage limit

Even after deletion, the same coupon code can be reused to create a new coupon if needed.

Things to consider

Always call this API after validation to ensure safe processing.
Once redeemed, the coupon cannot be used again.
A rollback strategy may be required if the payment fails.
Implement idempotency or safeguards to prevent duplicate redemption from repeated requests.

Coupon Redeem API (v2)