---
title: "POST /api/v4.0/integrations/coupons/{code}/validate"
method: POST
path: "/api/v4.0/integrations/coupons/{code}/validate"
---

# POST /api/v4.0/integrations/coupons/{code}/validate

`POST /api/v4.0/integrations/coupons/{code}/validate`

This API validates a single coupon identified by {code} and checks its eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves the coupon by creating a lock reference. This ensures the coupon cannot be used by others during the lock session, preventing conflicts or double usage. By default, the lock flag is False, allowing only validation without reserving the coupon.

## Path parameters

- `code` string, required

## Request body

- object
  - `customerId` string, required — Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.
  - `email` string — Customer's email address. Required if your account uses email-based channel merging.
  - `mobile` string — Customer's mobile number. Required if your account uses mobile-based channel merging.
  - `lock` boolean — Indicates whether the request is intended to validate the coupon or to lock it for a future redemption.
  - `lockReference` string — Required only if the lock flag is set to True and you need to validate and lock a new or updated list of coupons within an existing lock session.
  - `lockDuration` integer — Represents the number of minutes for which a coupon will be locked if the lock flag is set to True.
  - `merchantId` string — This parameter is required only if the coupon is designed to apply to specific merchants.
  - `collectionId` string — This parameter is required only if the coupon is configured to apply to specific collections.
  - `collectionsIds` string[] — This parameter is required only when the coupon is configured to apply to specific collections.
  - `totalPurchaseAmount` number — This parameter represents the total value of the purchase where the coupon will be applied.

## Response `200`

Coupon validated successfully

- object
  - `valid` boolean — Indicates whether the coupon is valid to be used by the customer or not.
  - `coupon` Coupon
    - `code` string — The generated coupon code that the customer will use.
    - `type` 'shipping' | 'fixed' | 'percentage' | 'product' | 'percentage-fees' | 'fixed-cashback' | 'percentage-cashback' — Type of the coupon, such as fixed amount, percentage discount, free shipping, cashback or product-specific coupon.
    - `value` number — The monetary value or percentage value of the coupon, depending on its type.
    - `usageLimit` number — The total number of times the coupon can be used across all customers.
    - `limitPerCustomer` number — The number of times a single customer can use the coupon.
    - `startDate` string, date-time — The date and time when the coupon becomes valid and can be used.
    - `expiryDate` string, date-time — The date and time when the coupon will expire and no longer be valid.
    - `capping` number — The maximum discount or value cap that the coupon can offer, even if the discount calculation exceeds this value.
    - `minReward` number — Specifies the minimum discount value a customer is guaranteed to receive when using a percentage-based discount coupon.
    - `minOrderValue` number — The minimum order value required for the coupon to be applied.
    - `entitledProductIds` string[] — A list of product IDs that are eligible for the coupon.
    - `entitledVariantIds` string[] — A list of product variant IDs that are eligible for the coupon.
    - `entitledCollectionIds` string[] — A list of collection IDs that are eligible for the coupon.
    - `entitledMerchantIds` string[] — A list of merchant external IDs that are eligible to redeem the coupon.
    - `combinesWith` object
      - `orderDiscounts` boolean — Indicates if the coupon can be combined with order-level discounts.
      - `productDiscounts` boolean — Indicates if the coupon can be combined with product-specific discounts.
      - `shippingDiscounts` boolean — Indicates if the coupon can be combined with shipping discounts.
  - `lockReference` string — The unique reference code associated with the coupon lock session.
  - `dateToExpire` string, date-time — The exact date and time when the coupon lock will expire.

---

[API](https://skmtc.net/gameballers/apis/gameball-api.md) · [All operations](https://skmtc.net/gameballers/apis/gameball-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gameballers/gameball-api/revisions/2e4a8bfe2291/schema)