> ## Documentation Index > Fetch the complete documentation index at: https://docs.mention-me.com/llms.txt > Use this file to discover all available pages before exploring further. # Validate coupon code > Check whether a single-use coupon code is valid and return details about the reward it is allowed to be redeemed for. In this case we assume that Mention Me has issued a coupon to a customer or potential customer. This coupon could be a single-use coupon previously given to Mention Me in a batch of coupons. Or it could be a single-use coupon generated directly by Mention Me. The customer could have been promised the reward as a potential new customer (referee), for referring another customer (referrer) or just because they've been offered an incentive to come to store (incentive for action). The customer then brings the coupon to the merchant intending to redeem it. This endpoint allows the merchant (or a third party) to check if the coupon is still valid and is capable of being used to redeem a reward at Mention Me. This endpoint allows you to validate a coupon code before attempting to redeem it. It will check: - Whether the coupon exists for your merchant - Whether the coupon is currently valid (not expired, not barred, has started) - Whether the coupon is attached to an unredeemed reward and hence can be spent There are three responses (validityResponseCode): - FOUND_REDEEMABLE - this means the coupon is found, is valid and can be used to spend the provided reward. - FOUND_NOT_REDEEMABLE - this means the coupon is known to Mention Me - but is either not valid or has already been spent. - NOT_FOUND - the coupon is not known to Mention Me. There is also a human-readable description of the response code (validityResponseDescription). Use the validityResponseCode to decide on the outcome (the human-readable description could change). If the coupon is found, the response will include details about the reward such as the discount amount, type (e.g., percentage or fixed amount), currency, and description. If the coupon is not redeemable, the validityResponseDescription will indicate why it cannot be used. If the coupon is not found, the response won't have additional details. If you find the coupon is valid and then allow the customer to redeem the coupon you should then subsequently tell us about the purchase they made, including the coupon code so that we can mark it as redeemed. Once you've done that the coupon will of course be invalid if requested again. You can do this using the Record Order API endpoint (if you have the email address of the customer) or the Redeem Coupon API endpoint (if you don't have the email address of the customer). **Scopes:** `customers:read`, `rewards:read` **Rate limits:** 300 requests per 5 minutes. Shared across all 'coupons' endpoints. ## OpenAPI ````yaml /openapi/merchant_api.oas.json get /api/merchant/v2/coupons/validate/{coupon_code} openapi: 3.0.0 info: title: Merchant API description: Interact directly with the Mention Me platform using our REST API. termsOfService: https://mention-me.com/help/tnc_f/site contact: name: Mention Me url: https://mention-me.com email: support@mention-me.com version: v2 servers: - url: https://mention-me.com description: Production - url: https://demo.mention-me.com description: Demo security: - Bearer: [] tags: - name: Coupons - name: Customers - name: Referee paths: /api/merchant/v2/coupons/validate/{coupon_code}: get: tags: - Coupons summary: Validate coupon code description: >- Check whether a single-use coupon code is valid and return details about the reward it is allowed to be redeemed for. In this case we assume that Mention Me has issued a coupon to a customer or potential customer. This coupon could be a single-use coupon previously given to Mention Me in a batch of coupons. Or it could be a single-use coupon generated directly by Mention Me. The customer could have been promised the reward as a potential new customer (referee), for referring another customer (referrer) or just because they've been offered an incentive to come to store (incentive for action). The customer then brings the coupon to the merchant intending to redeem it. This endpoint allows the merchant (or a third party) to check if the coupon is still valid and is capable of being used to redeem a reward at Mention Me. This endpoint allows you to validate a coupon code before attempting to redeem it. It will check: - Whether the coupon exists for your merchant - Whether the coupon is currently valid (not expired, not barred, has started) - Whether the coupon is attached to an unredeemed reward and hence can be spent There are three responses (validityResponseCode): - FOUND_REDEEMABLE - this means the coupon is found, is valid and can be used to spend the provided reward. - FOUND_NOT_REDEEMABLE - this means the coupon is known to Mention Me - but is either not valid or has already been spent. - NOT_FOUND - the coupon is not known to Mention Me. There is also a human-readable description of the response code (validityResponseDescription). Use the validityResponseCode to decide on the outcome (the human-readable description could change). If the coupon is found, the response will include details about the reward such as the discount amount, type (e.g., percentage or fixed amount), currency, and description. If the coupon is not redeemable, the validityResponseDescription will indicate why it cannot be used. If the coupon is not found, the response won't have additional details. If you find the coupon is valid and then allow the customer to redeem the coupon you should then subsequently tell us about the purchase they made, including the coupon code so that we can mark it as redeemed. Once you've done that the coupon will of course be invalid if requested again. You can do this using the Record Order API endpoint (if you have the email address of the customer) or the Redeem Coupon API endpoint (if you don't have the email address of the customer). **Scopes:** `customers:read`, `rewards:read` **Rate limits:** 300 requests per 5 minutes. Shared across all 'coupons' endpoints. operationId: get_merchant_api_coupons_validate parameters: - name: coupon_code in: path description: The coupon code to validate required: true schema: type: string responses: '200': description: Coupon validation result with reward details content: application/json: schema: $ref: '#/components/schemas/CouponValidationOutput' '401': description: Required scopes are missing. content: application/problem+json: schema: $ref: '#/components/schemas/UnauthorisedRFC7807Problem' '429': description: Rate limit exceeded. content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsRFC7807Problem' components: schemas: CouponValidationOutput: description: Validation status and reward details for a coupon code required: - validityResponseCode properties: validityResponseCode: description: >- System readable code indicating whether the coupon code is FOUND_REDEEMABLE, FOUND_NOT_REDEEMABLE or NOT_FOUND type: string validityResponseDescription: description: Human readable response indicating information about the code type: string default: null nullable: true rewardType: description: The type of reward (AMOUNT, PERCENTAGE, etc.) type: string default: null nullable: true rewardAmount: description: The amount or percentage value of the reward type: number format: float default: null nullable: true currencyCode: description: The currency code for the reward (e.g., GBP, USD) type: string default: null nullable: true description: description: Human-readable description of the reward type: string default: null nullable: true type: object UnauthorisedRFC7807Problem: properties: status: type: integer maximum: 599 minimum: 200 example: 401 type: type: string example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html title: type: string example: Unauthorized detail: type: string example: Missing at least one of the required scopes type: object TooManyRequestsRFC7807Problem: properties: status: type: integer maximum: 599 minimum: 200 example: 401 type: type: string example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html title: type: string example: Too Many Requests detail: type: string example: Rate limit exceeded for Client Id type: object securitySchemes: Bearer: type: http description: RFC8725 Compliant JWT bearerFormat: JWT scheme: bearer ````