Redeem coupons

When the user enters a coupon code in the in-app coupon exchange, call RedeemCouponAsync() to redeem the coupon. The in-app coupon exchange is the app screen where the user enters a coupon code, and the app builds it itself. When coupon redemption succeeds, the Hive Axyl server puts the items set for the coupon in the grant mail and sends it to the logged-in user's in-app mailbox. The user receives the items in this mailbox.

To call this method, the user must be logged in. If you have not registered the coupon module or activated the login session yet, first complete Install the module, initialize, and log in.

1. Prepare the coupon code

The coupon code you pass to RedeemCouponAsync() is the value that the operator issued in the Hive Console and the user entered in the in-app coupon exchange. The Hive Axyl server validates whether the code is correct.

1.1. Issue coupon codes

Coupon codes are generated when the operator issues a coupon in Hive Console > Coupon > Coupon Issuance and the coupon goes through approval. When issuing the coupon, the operator also sets the items and quantities to grant to users who redeem that coupon. How coupon codes are created differs by coupon type, as follows.

Bulk coupon: An 8-, 12-, or 16-character code automatically generated from random letters and numbers
Keyword coupon: A code of 8 to 20 letters or numbers that the operator sets directly

For the coupon issuance and approval procedures, see Coupon issuance.

Test coupons

To check the flow of entering a coupon code in the app and receiving the items before the official launch, use test coupons. When a bulk coupon is issued, up to 10 test coupons are issued with it. Test coupons can be used even before the usage start date, but cannot be used after the end date has passed. Other usage conditions are the same as for official coupons.

On the Test Coupons tab of the Coupon Issuance List popup, check the test coupon codes and whether they have been used. After the coupon reaches the Issued status, select the coupon title in the Hive Console > Coupon > Coupon Issuance list, and then select View Issuance List in the Coupon Details popup to open the Coupon Issuance List popup.

1.2. Coupon code format

A coupon code is a string of 8 to 20 letters and numbers and is not case-sensitive. Even if the user enters hyphens for readability, as in 1234-ABCD, the Hive Axyl server removes the hyphens before validation. Therefore, you may send the code from the app client without removing hyphens or changing case. However, the total length including hyphens cannot exceed 20 characters.

2. Request coupon redemption

RedeemCouponAsync

Call RedeemCouponAsync() to request redemption of the coupon code the user entered. When coupon redemption succeeds, the Hive Axyl server puts the items set for the coupon in the grant mail and asks the mailbox server to send it. When the mailbox server accepts the send request, the Hive Axyl server returns the ID of the grant mail in MailId of the response data. If the coupon code cannot be redeemed, RedeemCouponAsync() returns the result case in Response status that matches the reason.

Call parameters

Field name	Type	Required	Description
`request`	`CouponRedeemRequest`	Required	Request that holds the coupon code to redeem. Passing `null` throws `ArgumentNullException`
`context`	`ApiCallContext?`	Optional	Per-call settings object. Specify it to cancel the call or to apply a separate request policy, such as a timeout, to this call only. If omitted, the default values are used. Even if you cancel the call, a coupon redemption request that has already reached the Hive Axyl server may not be canceled. For details, see Core call context.

CouponRedeemRequest

Field name	Type	Required	Description
`CouponCode`	`string`	Required	The coupon code the user entered in the in-app coupon exchange. 8 to 20 letters and numbers, not case-sensitive. Even if it contains hyphens, the Hive Axyl server removes them before validation, and the total length including hyphens is 20 characters or less. Example: `ABCD1234EFGH`

Call example

See the example below and Response status for the success result of CouponRedeemCouponResult and the result cases (Outcome) of this method. For the result model and handling principles of common failures (Failure) returned when the request cannot be performed, see Common error handling.

The following example uses a switch statement to branch on every result case that RedeemCouponAsync() returns. The comment in each branch is the guidance to show in the in-app coupon exchange.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Coupon;
using UnityEngine;

// coupon: ICouponService registered during module initialization
ICouponService coupon = HiveCore.Resolve<ICouponService>();

// inputCode: Coupon code the user entered in the in-app coupon exchange
CouponRedeemCouponResult result = await coupon.RedeemCouponAsync(new CouponRedeemRequest
{
    CouponCode = inputCode,
});

switch (result)
{
    case CouponRedeemCouponResult.Success success:
        // The mailbox server accepted the send request for the grant mail.
        // Tell the user that the coupon was redeemed, and guide them to receive the items in the in-app mailbox.
        string mailId = success.Data.MailId;   // ID of the grant mail
        break;

    case CouponRedeemCouponResult.CouponCodeInvalidFormat:
        // The coupon code format is invalid, so ask the user to check the code.
        break;

    case CouponRedeemCouponResult.CouponCodeNotFound:
        // The coupon code does not exist or has been deleted, so ask the user to check the code.
        break;

    case CouponRedeemCouponResult.CouponDisabled:
        // Tell the user that the coupon cannot be used right now.
        break;

    case CouponRedeemCouponResult.CouponBeforeStart:
        // Ask the user to redeem the coupon again after the usage period starts.
        break;

    case CouponRedeemCouponResult.CouponExpired:
        // Tell the user that the coupon's usage period has ended.
        break;

    case CouponRedeemCouponResult.CouponAlreadyUsed:
        // Tell the user that the coupon has already been used.
        break;

    case CouponRedeemCouponResult.CouponAccountLimitExceeded:
        // Tell the user that this account can no longer redeem the coupon.
        break;

    case CouponRedeemCouponResult.CouponGroupLimitExceeded:
        // Tell the user that this account cannot redeem any more coupons in the same group.
        break;

    case CouponRedeemCouponResult.CouponTotalLimitExceeded:
        // Tell the user that the available quantity of this coupon code has been used up.
        break;

    // Handle common failures (network and server errors, common Failure codes)
    case CouponRedeemCouponResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.ExternalCode} {err.Message} (trace: {err.TraceId})");
        if (err.ExternalCode == "internal_error")
        {
            // The coupon has reverted to the unused state, so ask the user to try again with the same coupon code.
        }
        else
        {
            // Show a general failure message.
        }
        break;

    // A new result that this SDK version does not know: record it, and then treat it as a failure.
    case CouponRedeemCouponResult.UnknownOutcome unknown:
        Debug.LogWarning($"[Coupon] Unknown result: {unknown.Code} {unknown.RawJson}");
        // Show a general failure message.
        break;

    // Safety net: unhandled results
    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Response data

On success, the result is contained in Data (CouponRedeemResponseWrapperResponseData) of CouponRedeemCouponResult.Success. Use Data.MailId to find the grant mail in the user's received mail list.

Field name	Type	Required	Description
`Data.MailId`	`string`	Required	ID of the grant mail sent with the items set for the coupon. It is the original sent mail ID of the mailbox, so it is different from `MailRecipientId`, which you use to get received mail details or mark received mail as read
`Data.Meta`	`string?`	Optional	Additional information that the Hive Axyl server sent along with the result. A raw, unprocessed JSON string; `null` if there is no additional information

Response example

Unity

// success.Data (CouponRedeemResponseWrapperResponseData)
string mailId = success.Data.MailId;   // Example: "0196f7c3-8b2e-7f4d-a123-9c8d7e6f5a4b"
string? meta  = success.Data.Meta;     // null if there is no additional information

Response status

The returned object CouponRedeemCouponResult branches into one of the cases below. The Hive Axyl server validates the coupon code in this order: format, existence, usage conditions, usage status, and usage limits. If several conditions apply at the same time, it returns only the one result with the highest priority among them. In the table below, CouponCodeInvalidFormat through CouponTotalLimitExceeded follow this validation order.

RedeemCouponAsync() returns only the result case and does not return a message to show to the user. Therefore, decide the message for each result case yourself and show it in the in-app coupon exchange.

Result case	Description	App client handling
`Success`	Coupon redemption succeeded. The mailbox server accepted the send request for the grant mail, and the ID of that mail is held in `Data.MailId`.	Tell the user that the coupon was redeemed and guide them to receive the items in the in-app mailbox. For what to do next, see Claim the grant mail.
`CouponCodeInvalidFormat`	The coupon code format is invalid.	Ask the user to check the coupon code and enter it again
`CouponCodeNotFound`	The coupon code does not exist or has been deleted.	Ask the user to check the coupon code and enter it again
`CouponDisabled`	The coupon or the coupon code is disabled. This applies when coupon usage is Off in the Hive Console or the coupon code is inactive.	Tell the user that the coupon cannot be used right now
`CouponBeforeStart`	The coupon's usage period has not started yet.	Ask the user to redeem the coupon again after the usage period starts
`CouponExpired`	The coupon's usage period has ended.	Tell the user that the coupon's usage period has ended
`CouponAlreadyUsed`	The coupon has already been used.	Tell the user that the coupon has already been used
`CouponAccountLimitExceeded`	The per-account usage limit has been reached. The limit is set when the coupon is issued in the Hive Console.	Tell the user that this account can no longer redeem the coupon
`CouponGroupLimitExceeded`	The usage limit of the coupon group has been reached. In the Hive Console, the operator bundles multiple coupons of the same type into a coupon group to limit the number of uses per account at the group level. For details, see Coupon issuance.	Tell the user that this account cannot redeem any more coupons in the same group
`CouponTotalLimitExceeded`	The total usage limit of this coupon code has been reached. The limit is set when the coupon is issued in the Hive Console.	Tell the user that the available quantity of the coupon has been used up
`Failure`	Common Failure. This covers cases where the call could not be completed, such as a network error, and cases where the Hive Axyl server responded with one of the common Failure codes. The cause code is held in `Failure.Problem.ExternalCode`. If `ExternalCode` is `internal_error`, the coupon reverts to the unused state. `ExternalCode` is also `internal_error` when the grant mail could not be sent.	Handle it according to the Common error handling criteria. If it is `internal_error`, ask the user to try again with the same coupon code
`UnknownOutcome`	A new result that this SDK version does not know.	Treat it as a failure and record `Code` and `RawJson`. For the handling criteria, see Unknown results.

3. Claim the grant mail

Success means that the mailbox server accepted the send request for the grant mail, not that the user received the items. The Hive Axyl server treats the grant mail as successfully sent once the send request is accepted. The app server must check separately in the mailbox whether the user actually received the items.

Therefore, do not conclude that the item grant is complete from Success alone; handle the grant mail in the order described in Claim the items in the mailbox.

3.1. Grant mail sending information

The Hive Axyl server sends the grant mail with the following values. Use these values as the basis when you build the mailbox screen in the app or process the grant mail.

Item	Grant mail value	What to check in the app
Sender	It is "Admin".	A fixed value that does not change regardless of the language setting.
Language	The language that the Hive Axyl SDK sends with the `RedeemCouponAsync()` request. If the request has no language or the Hive Axyl server does not support the language, the mail is sent in Korean.	The Hive Axyl SDK puts the OS language it read during initialization in the request. If the app has its own language setting separate from the OS language, specify the language with SetLanguage() before redeeming the coupon.
Category	It is `DEFAULT`, the default mailbox category.	If the app client specifies a category with `MailCategory` when it retrieves the received mail list, the grant mail appears only when the list is retrieved with `DEFAULT` or without `MailCategory`.
Extension data	A JSON string that holds the UUID-format identifier of the redeemed coupon under the `couponId` key.	It is held in `Mail.MailExtension` in the response of Get received mail details. For the field descriptions, see Mail. Because the mailbox does not interpret this value, the app server reads and uses it when it processes the mail.

3.2. Claim the items in the mailbox

The items set for the coupon are delivered as attached items of the grant mail, and the process of the user receiving these items is handled with mailbox features. The Hive Axyl SDK mailbox only records the claim status of attached items and does not actually grant the items. Therefore, the app must implement the item grant and claim verification itself. For details, see Attached items.

Process the grant mail in the following order.

The app client loads the list of mail the user received with Get the received mail list. MailId of a list item is the ID of the original sent mail. The item whose MailId is the same as Data.MailId in the RedeemCouponAsync() response is the grant mail.
The app client calls Get received mail details with the MailRecipientId of the grant mail item and checks the attached items and Mail.MailExtension.
The app server checks the attached items and Mail.MailExtension and grants the items to the user.
After the app client receives the grant result from the app server, it calls Mark mail as read to update the attached item claim status. In this call, set Target to Attachment or All. For how to determine the claim status, see Distinguish the read status from the claim status.