ICouponService

The service that redeems, on the Hive Axyl server, coupon codes that app users enter. When a coupon is redeemed, mail containing the coupon's items is sent to the logged-in user's mailbox.

Interface: ICouponService
Namespace: Hive.Axyl.Coupon
Package: com.com2usplatform.hiveaxyl.coupon

Registration and retrieval

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Coupon;

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddCoupon();
});

ICouponService coupon = HiveCore.Resolve<ICouponService>();

Method summary

For the meaning of the 'Authentication' column, see Authentication requirement notation.

Method	Authentication	Description
RedeemCouponAsync	Session required	Redeems a coupon code and grants the coupon's items to the mailbox.

Common parameters

The last parameter of every method is ApiCallContext? context = null. If you omit it, the default values apply. For details, see Call context.

Every method takes the request body as the request parameter, and request is Required. The method descriptions below show only the request type and omit the parameter table. Check the fields of each request type in Data types.

Exceptions

ArgumentNullException: When request is null

Common Failure codes

The server responds with the following codes, but they are not feature-level results, so they branch to Failure, not Outcome. The cause code is held in Failure.Problem.ExternalCode. For the result branches and how to branch, see Core result model.

bad_request: Invalid request
invalid_parameter: Request parameter format error
missing_field: A required field, or a required header itself such as X-App-Id, is missing
missing_app_id: The X-App-Id header was sent, but its value is empty
unauthorized: The authentication token is missing or invalid
token_expired: Authentication token expired
forbidden: No permission for the request
resource_not_found: Requested resource not found
method_not_allowed: Request method not allowed
resource_conflict: Conflict between the request and the resource state
unprocessable_content: Request content that cannot be processed
rate_limit_exceeded: Request frequency exceeded the allowed limit
internal_error: Internal server error
service_unavailable: Service temporarily unavailable

Methods

RedeemCouponAsync

Redeems the coupon code the app user entered. If redemption succeeds, mail containing the coupon's items is sent to the logged-in user's mailbox, and the ID of the sent mail is returned as Data.MailId. If Failure is returned because of an internal server error, the coupon reverts to the unused state. The same applies when the server fails to send the mail, and in that case Problem.ExternalCode holds internal_error.

Unity

Task<CouponRedeemCouponResult> RedeemCouponAsync(CouponRedeemRequest request, ApiCallContext? context = null);

Request: CouponRedeemRequest
Response: CouponRedeemResponseWrapperResponseData
Authentication: Session required

Result cases — CouponRedeemCouponResult

The server validates the coupon code in this order: format, existence, usage conditions, usage status, and usage limits. Even if several conditions apply, only the one result with the highest priority is returned, and the table below lists the result cases in this validation order.

Result case	Wire code	Description
`Success`	—	The coupon was redeemed. The ID of the mail that granted the items is held in `Data.MailId`.
`CouponCodeInvalidFormat`	`coupon_code_invalid_format`	The coupon code format is invalid.
`CouponCodeNotFound`	`coupon_code_not_found`	The coupon code does not exist or has been deleted.
`CouponDisabled`	`coupon_disabled`	The coupon or the coupon code is disabled.
`CouponBeforeStart`	`coupon_before_start`	The coupon's usage period has not started yet.
`CouponExpired`	`coupon_expired`	The coupon's usage period has ended.
`CouponAlreadyUsed`	`coupon_already_used`	The coupon has already been used.
`CouponAccountLimitExceeded`	`coupon_account_limit_exceeded`	The per-account usage limit has been used up.
`CouponGroupLimitExceeded`	`coupon_group_limit_exceeded`	The per-group usage limit has been used up.
`CouponTotalLimitExceeded`	`coupon_total_limit_exceeded`	The total usage limit of this coupon code has been used up.
`UnknownOutcome`	`UNKNOWN`	A new result that this SDK version does not know.
`Failure`	`FAILURE`	The call could not be completed. The common Failure codes also branch to this case.

Grant mail

The server treats the grant as successful once the mailbox accepts the request to send the grant mail. Therefore, the app server must check separately in the mailbox whether the app user received the mail and claimed the items. The grant mail is sent as follows.

Language: The request language. If the request has no language or the server does not support the language, the mail is sent in Korean.
Category: DEFAULT, the default mailbox category
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, and because the mailbox does not interpret this value, the app server reads and uses it when it processes the mail.

To change the request language, see SetLanguage().

Call example

Unity

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

var result = await coupon.RedeemCouponAsync(new CouponRedeemRequest
{
    CouponCode = inputCode,   // Coupon code the app user entered
});

switch (result)
{
    case CouponRedeemCouponResult.Success success:
        string mailId = success.Data.MailId;   // ID of the mail that granted the items
        break;

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

    case CouponRedeemCouponResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // Other result cases and UnknownOutcome
        break;
}

Data types

CouponRedeemRequest

A coupon redemption request.

Field	Type	Required	Description
`CouponCode`	`string`	Required	The coupon code the app user entered. It consists of 8 to 20 letters and digits and is not case-sensitive. The server removes hyphens added for readability before validation, so you can send the code as entered. However, the total length including hyphens must not exceed 20 characters. Example: `ABCD1234EFGH`

CouponRedeemResponseWrapperResponseData

The coupon redemption result.

Field	Type	Required	Description
`MailId`	`string`	Required	The ID of the mail that granted the coupon's items. It is a sent mail ID of the mailbox, so it is different from `MailRecipientId`, which you use when you handle received mail.
`Meta`	`string?`	Optional	Additional information the server sent along with the result. It is held as the raw, unprocessed JSON string.