> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Validate Single Coupon
> Validate a single coupon and optionally lock it for exclusive use.
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.
Alternatively, you can use the **coupon code directly** when placing an order instead of the **hold reference**. For more details, refer to the **Order API**.
**Channel Merging Available**\
If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer's mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.
For more information, head to the [Omni-Channel Handling Guide](/tutorials/experiences/more/omni-channel).
**Security**: Requires **apikey** and **secretkey** headers.
## OpenAPI
````yaml POST /api/v4.0/integrations/coupons/{code}/validate
openapi: 3.1.0
info:
title: Gameball API
description: >-
Gameball REST API v4.0 - Complete API reference for integrating loyalty,
gamification, and customer engagement features
version: 4.0.0
servers:
- url: https://api.gameball.co
security:
- bearerAuth: []
paths:
/api/v4.0/integrations/coupons/{code}/validate:
post:
description: >-
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.
parameters:
- name: code
in: path
required: true
schema:
type: string
description: The coupon code you want to validate.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerId
properties:
customerId:
type: string
description: >-
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:
type: string
description: >-
Customer's email address. Required if your account uses
email-based channel merging.
mobile:
type: string
description: >-
Customer's mobile number. Required if your account uses
mobile-based channel merging.
lock:
type: boolean
description: >-
Indicates whether the request is intended to validate the
coupon or to lock it for a future redemption.
lockReference:
type: string
description: >-
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:
type: integer
description: >-
Represents the number of minutes for which a coupon will be
locked if the lock flag is set to True.
merchantId:
type: string
description: >-
This parameter is required only if the coupon is designed to
apply to specific merchants.
collectionId:
type: string
description: >-
This parameter is required only if the coupon is configured
to apply to specific collections.
collectionsIds:
type: array
items:
type: string
description: >-
This parameter is required only when the coupon is
configured to apply to specific collections.
totalPurchaseAmount:
type: number
description: >-
This parameter represents the total value of the purchase
where the coupon will be applied.
responses:
'200':
description: Coupon validated successfully
content:
application/json:
schema:
type: object
properties:
valid:
type: boolean
description: >-
Indicates whether the coupon is valid to be used by the
customer or not.
coupon:
$ref: '#/components/schemas/Coupon'
lockReference:
type: string
description: >-
The unique reference code associated with the coupon lock
session.
dateToExpire:
type: string
format: date-time
description: The exact date and time when the coupon lock will expire.
security:
- apiKey: []
secretKey: []
components:
schemas:
Coupon:
type: object
properties:
code:
type: string
description: The generated coupon code that the customer will use.
type:
type: string
enum:
- shipping
- fixed
- percentage
- product
- percentage-fees
- fixed-cashback
- percentage-cashback
description: >-
Type of the coupon, such as fixed amount, percentage discount, free
shipping, cashback or product-specific coupon.
value:
type: number
description: >-
The monetary value or percentage value of the coupon, depending on
its type.
usageLimit:
type: number
description: >-
The total number of times the coupon can be used across all
customers.
limitPerCustomer:
type: number
description: The number of times a single customer can use the coupon.
startDate:
type: string
format: date-time
description: The date and time when the coupon becomes valid and can be used.
expiryDate:
type: string
format: date-time
description: >-
The date and time when the coupon will expire and no longer be
valid.
capping:
type: number
description: >-
The maximum discount or value cap that the coupon can offer, even if
the discount calculation exceeds this value.
minReward:
type: number
description: >-
Specifies the minimum discount value a customer is guaranteed to
receive when using a percentage-based discount coupon.
minOrderValue:
type: number
description: The minimum order value required for the coupon to be applied.
entitledProductIds:
type: array
items:
type: string
description: A list of product IDs that are eligible for the coupon.
entitledVariantIds:
type: array
items:
type: string
description: A list of product variant IDs that are eligible for the coupon.
entitledCollectionIds:
type: array
items:
type: string
description: A list of collection IDs that are eligible for the coupon.
entitledMerchantIds:
type: array
items:
type: string
description: >-
A list of merchant external IDs that are eligible to redeem the
coupon.
combinesWith:
type: object
properties:
orderDiscounts:
type: boolean
description: >-
Indicates if the coupon can be combined with order-level
discounts.
productDiscounts:
type: boolean
description: >-
Indicates if the coupon can be combined with product-specific
discounts.
shippingDiscounts:
type: boolean
description: Indicates if the coupon can be combined with shipping discounts.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
secretKey:
type: apiKey
in: header
name: secretkey
````