Coupon API

This page describes the Hive Axyl Server API that an app server or Web Coupon Exchange calls directly from the Coupon feature. This API validates the coupon code entered by the player and delivers the items configured for the coupon to the player's mailbox.

Redeem coupon

POST /coupon/v1/redeem

Redeems the coupon code entered by the player.

It delivers the items configured for the coupon to the player's mailbox and returns the mail receipt number (mailId).

Before calling the API

Item	Value
Caller	`App server` or `web coupon exchange`
Base URL	Live: `https://commerce-api.hiveaxyl.com` Test: `https://test-api.hiveaxyl.com`
Authentication	`Authorization: Bearer {access-token}`

Warning

In the authentication header, include the Bearer access token received from issuing a token or from the login process. The access token is used to validate the request permission and target app, so do not leave it in logs or error messages.

Delivered mail

Delivery completion criterion - Delivery is considered successful when the mailbox accepts the delivery request. The app server must separately check the mailbox to determine whether the player actually claimed the item.
Language - Follows the Accept-Language header in the request. If the language is not supported or the header is missing, the mail is sent in Korean (ko).
Category (mailCategory) - Not specified, so the mail is sent with the mailbox default value (DEFAULT).
Extension information (mailExtension) - A JSON string containing the following field is included. The mailbox does not interpret this value and stores it as is, so the app server can read and use it when processing mail receipt.
- couponId - Identifier (UUID) of the redeemed coupon

Call parameters

Name	Location	Type	Required	Description
`X-App-Id`	`header`	`string`	`true`	Project identifier header.
`X-SDK-Version`	`header`	`string`	`false`	Client SDK version information.
`X-Platform`	`header`	`string`	`false`	Platform information. Example: `Android`, `iOS`, `STEAM`
`X-OS-Version`	`header`	`string`	`false`	Operating system version information.
`Accept-Language`	`header`	`string`	`false`	Client language setting. Example: `en-US`, `ko-KR`
`traceparent`	`header`	`string`	`false`	W3C Trace Context header for distributed tracing.
`User-Agent`	`header`	`string`	`false`	User-Agent information of the client application.
body	body	`CouponRedeemRequest`	`true`	Coupon redemption request information.

Request body CouponRedeemRequest

Field	Type	Required	Description
`couponCode`	`string`	`true`	Coupon code. Use English letters and numbers. The total length, including hyphens, must be 8 to 20 characters. Hyphens for input convenience (for example, `1234-ABCD`) are removed by the server before validation, so you may include them. The code is not case-sensitive.

Call example

curl

curl -X POST 'https://test-api.hiveaxyl.com/coupon/v1/redeem' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-App-Id: app.example.game' \
  -H 'X-SDK-Version: 4.23.1' \
  -H 'X-Platform: app.example.game' \
  -H 'X-OS-Version: Android 12' \
  -H 'Accept-Language: en-US' \
  -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
  -H 'User-Agent: HiveAxylClient/1.0 (Android 12; Mobile)' \
  -d '{
    "couponCode": "ABCD1234EFGH"
  }'

Response

For the common data, meta, error body, and product common error codes, see Responses and errors. This section describes the object actually returned by this API and API-specific handling.

Success response data object

Field	Type	Description
`data.mailId`	`string`	Mail receipt number.

Response examples

200 OKAccountLimitExceededAlreadyUsedBeforeStartCodeInvalidFormatCodeNotFoundCouponDisabledExpiredGroupLimitExceededTotalLimitExceededInternalError

{
  "data": {
    "mailId": "0196f7c3-8b2e-7f4d-a123-9c8d7e6f5a4b"
  },
  "meta": null
}

{
  "code": "coupon_account_limit_exceeded",
  "detail": "The per-account usage limit has been exceeded.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 3001,
    "message": "The per-account usage limit has been exceeded."
  },
  "status": 400,
  "title": "Account Limit Exceeded",
  "type": "/errors/coupon/coupon-account-limit-exceeded"
}

{
  "code": "coupon_already_used",
  "detail": "This coupon has already been used.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 2005,
    "message": "This coupon has already been used."
  },
  "status": 400,
  "title": "Already Used",
  "type": "/errors/coupon/coupon-already-used"
}

{
  "code": "coupon_before_start",
  "detail": "The coupon is not yet available for use.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 2001,
    "message": "The coupon is not yet available for use."
  },
  "status": 400,
  "title": "Before Start",
  "type": "/errors/coupon/coupon-before-start"
}

{
  "code": "coupon_code_invalid_format",
  "detail": "The coupon code format is invalid.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 1002,
    "message": "The coupon code format is invalid."
  },
  "status": 400,
  "title": "Code Invalid Format",
  "type": "/errors/coupon/coupon-code-invalid-format"
}

{
  "code": "coupon_code_not_found",
  "detail": "The coupon code does not exist or has been deleted.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 1001,
    "message": "The coupon code does not exist or has been deleted."
  },
  "status": 400,
  "title": "Code Not Found",
  "type": "/errors/coupon/coupon-code-not-found"
}

{
  "code": "coupon_disabled",
  "detail": "The coupon or coupon code is disabled.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 1003,
    "message": "The coupon or coupon code is disabled."
  },
  "status": 400,
  "title": "Coupon Disabled",
  "type": "/errors/coupon/coupon-disabled"
}

{
  "code": "coupon_expired",
  "detail": "The coupon usage period has expired.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 2002,
    "message": "The coupon usage period has expired."
  },
  "status": 400,
  "title": "Expired",
  "type": "/errors/coupon/coupon-expired"
}

{
  "code": "coupon_group_limit_exceeded",
  "detail": "The per-group usage limit has been exceeded.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 3002,
    "message": "The per-group usage limit has been exceeded."
  },
  "status": 400,
  "title": "Group Limit Exceeded",
  "type": "/errors/coupon/coupon-group-limit-exceeded"
}

{
  "code": "coupon_total_limit_exceeded",
  "detail": "The total usage limit for this code has been exceeded.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 3003,
    "message": "The total usage limit for this code has been exceeded."
  },
  "status": 400,
  "title": "Total Limit Exceeded",
  "type": "/errors/coupon/coupon-total-limit-exceeded"
}

{
  "code": "internal_error",
  "detail": "An unexpected error occurred.",
  "instance": "/coupon/v1/redeem",
  "status": 500,
  "title": "Internal Server Error",
  "type": "/errors/common/internal-error"
}

API-specific notes

If coupon redemption fails, the API returns an HTTP 400 response with a detailed error code (outcome.code). Validation is performed in the order of format -> existence -> usage conditions -> usage status and limits. If multiple error conditions apply at the same time, only the error with the highest priority is returned.

Response status

Status	Content type	Meaning	Response header	Response body or handling
`200`	`application/json`	Coupon redemption succeeded	-	`data.mailId` contains the mail receipt number.
`400`	`application/problem+json`	Coupon code, usage condition, or usage limit validation failed	-	Check the failure reason with `code` and `outcome.code`.
`500`	`application/problem+json`	Server error	-	A DB processing failure, mailbox delivery failure, or similar error occurred. The coupon is restored to an unused state.

API-specific error codes

Code	`outcome.code`	Condition	Handling
`coupon_code_not_found`	`1001`	The coupon code does not exist or has been deleted.	Ask the player to check the coupon code again.
`coupon_code_invalid_format`	`1002`	The coupon code format is invalid.	Check whether it uses the 8 to 20 character alphanumeric format.
`coupon_disabled`	`1003`	The coupon or code is disabled.	Check the coupon operation status.
`coupon_before_start`	`2001`	The coupon is not yet available for use.	Check the coupon start time.
`coupon_expired`	`2002`	The usage period has expired.	Check whether the coupon is available for use.
`coupon_already_used`	`2005`	The coupon has already been used.	Check the usage history.
`coupon_account_limit_exceeded`	`3001`	The per-account usage limit has been exceeded.	Check whether the same account has already used it.
`coupon_group_limit_exceeded`	`3002`	The group usage limit has been exceeded.	Check the usage limit for the coupon group.
`coupon_total_limit_exceeded`	`3003`	The total usage limit for this code has been exceeded.	Check the overall usage limit for the coupon code.