Changed on

Validates a list of coupons and checks their eligibility for use by a customer. Every coupon must pass - the first failure ends the call and nothing is locked. Describe the cart as well, and each coupon is additionally matched against its merchant, branch, collection, category and product restrictions. Set the lock flag to True to reserve the coupons under one lock session. By default the lock flag is False, allowing only validation without reserving the coupons.

post/api/v4.0/integrations/coupons/validate

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/coupons/validate
  • Auth: API key in header apikey and API key in header secretkey

Request body

customerIdstring 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.

emailstring

Customer's email address. Required if your account uses email-based channel merging.

mobilestring

Customer's mobile number. Required if your account uses mobile-based channel merging.

couponsstring[] required

A list of coupon codes to validate.

lockboolean

Indicates whether the request is intended to validate the coupon or to lock it for a future redemption.

lockReferencestring

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.

lockDurationinteger

Represents the number of minutes for which a coupon will be locked if the lock flag is set to True.

merchantIdstring

Cart-level. The merchant the order is placed with. Required if the coupon is restricted to specific merchants.

branchIdstring

Cart-level. The branch or outlet the order is placed at. Required if the coupon is restricted to specific branches. There is no plural or per-item form.

collectionIdstring

Item-level. A collection the basket touches. Evaluated together with collectionsIds as a single list. Ignored when lineItems is present.

collectionsIdsstring[]

Item-level. Every collection the basket touches. Maximum 200 values. Ignored when lineItems is present.

categoriesstring[]

Item-level. Every category the basket touches. These are free-text category names, not IDs. Maximum 200 values. Ignored when lineItems is present.

productsIdsstring[]

Item-level. Every product ID in the basket. Maximum 200 values. Ignored when lineItems is present.

totalPurchaseAmountnumber

Cart-level. The total value of the purchase the coupon will be applied to. Checked against the coupon's minOrderValue. Sending this field describes a cart only when the coupon carries a minOrderValue; for those coupons it switches on full restriction enforcement, and omitting it is rejected the same way a value below the minimum is.

Example request

{
  "merchantId": "cairo-downtown",
  "branchId": "branch-14",
  "categories": [
    "Audio",
    "TV"
  ]
}

Response

Coupons validated successfully

validboolean

Indicates whether the coupons are valid.

lockReferencestring

The unique reference code associated with the coupon lock session.

dateToExpirestring date-time

The exact date and time when the coupon lock will expire.

Changes

  • 448cb739d380Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • d41638533261Revision changes
    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      the endpoint scheme security apiKey AND secretKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status