Coupon Redeem API

The Vivoldi Coupon Redeem API marks an issued coupon as redeemed.

Instead of handling it manually in the dashboard, you can process redemption automatically via API.
Each request decreases the remaining usage count, and once the limit is reached, further redemption is blocked.

This API is available on the Personal plan or higher.

PUT

/api/coupon/v1/redeem 

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

Request Parameters

cpnNo string required
Coupon number.
onsitePwd string
On-site coupon password. Required if a password is set for the on-site coupon.
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. 
{
    "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

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 Coupon Password Handling

The onsitePwd field is required when a coupon has a password configured.

It is typically used in offline or in-store scenarios where staff verify the password before processing redemption.

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.