Validate Coupon

Endpoint used to validate whether a coupon code can be applied to a checkout

Request Example

curl --request POST 'https://api.mayar.id/hl/v2/coupons/validate' \
--header 'Authorization: Bearer Paste-Your-API-Key-Here' \
--data '{
    "couponCode": "HARIBAIK",
    "paymentLinkId": "4d26ea37-d093-4b92-8f5f-0faec64d65b0",
    "amount": 0,
    "customerEmail": "",
    "tickets": []
}'

Response Example 200

{
    "statusCode": 200,
    "messages": "success",
    "data": {
        "valid": true,
        "coupon": {
            "id": "08d233e9-91bc-4d9b-afc2-1dbbe38a1186",
            "code": "HARIBAIK",
            "discountType": "percentage",
            "discountValue": 10,
            "minimumPurchase": null,
            "eligibleCustomerType": "all"
        }
    }
}

Endpoint:

Production

https://api.mayar.id/hl/v2/coupons/validate

https://api.mayar.club/hl/v2/coupons/validate

Authorization

Authorization · string · required

Example:

Authorization | Bearer Paste-Your-API-Key-Here

Request Body

couponCode · string · required

Coupon code applied to the checkout.

paymentLinkId · string · required

Unique identifier of the payment link the coupon is applied to.

amount · number | integer

Transaction amount used to check the minimum-purchase requirement. Defaults to 0 when omitted.

customerEmail · string

Email address of the customer performing the checkout. Required to validate coupons restricted to new or old customers.

membershipTierId · string

Membership tier ID. Used together with paymentLinkType of membership_payment to resolve the payment link for membership checkouts.

paymentLinkType · string

Type of the payment link (example: membership_payment).

tickets · array

List of selected tickets for the checkout. Leave empty if not applicable.

Response

Successful Response

Main Structure (Root)

statusCode · integer

Status code from API.

messages · string

Status message that describes the status code.

data · object

Coupon validation result.

data Structure (Object)

valid · boolean

Indicates whether the coupon is valid for the checkout.

coupon · object

Object containing the validated coupon details.

coupon.id · string<uuid>

Unique identifier of the coupon.

coupon.code · string

Coupon code applied to the checkout.

coupon.discountType · string

Type of discount applied (monetary or percentage).

coupon.discountValue · number

Discount value based on the discount type.

coupon.minimumPurchase · number | null

Minimum purchase amount required to use the coupon. Returns null if not set.

coupon.eligibleCustomerType · string

Type of customers eligible to use the coupon (all, new, or old).

Errors

This endpoint returns a messages string describing why a coupon cannot be applied. The notable cases:

400 Validation Error · object

Returned with messages: "Validation Error" when the request body fails validation (e.g. missing couponCode or paymentLinkId).

404 Coupon not found · object

Returned with messages: "Gagal! Kode diskon ini tidak ditemukan." when the coupon does not exist or is not valid for the payment link.

400 Coupon inactive · object

Returned with messages: "Gagal! Kode diskon ini sudah tidak aktif." when the discount is inactive.

400 Coupon not yet active · object

Returned with messages: "Gagal! Kode diskon ini belum berlaku dan tidak dapat digunakan." when the discount start date has not been reached.

400 Coupon expired · object

Returned with messages: "Gagal! Kode diskon ini telah kadaluarsa dan tidak dapat digunakan." when the discount has expired.

400 Excluded product type · object

Returned with messages: "Gagal! Kode diskon tidak dapat digunakan untuk produk {productLabel}" when the payment link type is not eligible for discounts (e.g. payment requests or fundraising links).

400 Minimum purchase not met · object

Returned with messages: "Kode diskon ini hanya berlaku untuk transaksi dengan harga minimal {amount}." when amount is below the discount’s minimum purchase.

400 Customer eligibility · object

Returned with a messages string explaining that the coupon is restricted to new or old (existing) customers when customerEmail does not satisfy the eligibility rule.

400 Usage limit reached · object

Returned with messages: "Gagal! Kode diskon telah mencapai batas pemakaian dan tidak dapat digunakan kembali." when the coupon has reached its usage limit.