Skip to main content
POST
/
coupons
/
verify
Verify coupon
curl --request POST \
  --url https://store.salesive.com/api/v1/coupons/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-shop-id: <api-key>' \
  --data '
{
  "code": "SUMMER20",
  "orderId": "67890abcdef1234567890abc"
}
'
{
  "status": 200,
  "success": true,
  "message": "Coupon is valid",
  "data": {
    "_id": "<string>",
    "code": "<string>",
    "type": "fixed",
    "discount": 123,
    "discountAmount": 123,
    "minimumOrderAmount": 123,
    "startDate": "2023-11-07T05:31:56Z",
    "endDate": "2023-11-07T05:31:56Z",
    "title": "<string>"
  }
}

​
Request

POST /coupons/verify
Content-Type: application/json
x-shop-id: {shopId}
Authorization: Bearer {token}
{
  "code": "SUMMER20",
  "orderId": "67890abcdef1234567890abc"
}

​
Headers

HeaderTypeDescription
Content-TypestringAlways set to application/json.
x-shop-idstringShop identifier to associate the user with your store.
AuthorizationstringOptional Bearer token for authenticated requests.
This endpoint supports both authenticated and unauthenticated requests. Authentication is optional but recommended to validate user-specific coupon usage limits.

​
Body parameters

FieldTypeRequiredDescription
codestringYesCoupon code to verify (case-insensitive).
orderIdstringNoOrder ID to validate coupon against order total.

​
Successful response

{
    "status": 200,
    "success": true,
    "message": "Coupon is valid",
    "data": {
        "_id": "67890abcdef1234567890abc",
        "code": "SUMMER20",
        "type": "percentage",
        "discount": 20,
        "discountAmount": 200,
        "minimumOrderAmount": 500,
        "startDate": "2025-01-01T00:00:00.000Z",
        "endDate": "2025-12-31T23:59:59.000Z",
        "title": "20% off order above 500"
    }
}

​
Response fields

FieldTypeDescription
_idstringUnique coupon identifier.
codestringCoupon code.
typestringCoupon type: fixed or percentage.
discountnumberDiscount value (fixed amount or percentage).
discountAmountnumberCalculated discount amount based on order subtotal.
minimumOrderAmountnumberMinimum order amount required to use the coupon.
startDatestringDate when the coupon becomes active.
endDatestringDate when the coupon expires.
titlestringHuman-readable description of the coupon discount offer.

​
Validation checks

The endpoint performs the following validations:
Coupon exists and is active
Coupon belongs to the specified shop
Coupon is within valid date range (between start and end dates)
Global usage limit has not been exceeded
Per-user usage limit has not been exceeded (for authenticated users)
Order meets minimum amount requirement (if orderId provided)

​
Error responses

​
Invalid coupon code

{
    "status": 404,
    "success": false,
    "message": "Invalid coupon code"
}

​
Coupon expired

{
    "status": 400,
    "success": false,
    "message": "Coupon has expired"
}

​
Minimum order not met

{
    "status": 400,
    "success": false,
    "message": "Minimum order amount of 500 required to use this coupon"
}

​
Usage limit reached

{
    "status": 400,
    "success": false,
    "message": "You have already used this coupon 1 time(s)"
}

Authorizations

​
Authorization
string
header
required

JWT issued by the Salesive Store API for authenticated shoppers.

​
x-shop-id
string
header
required

Optional storefront identifier sent as a header to scope responses to a specific shop. Try It requests remember this value once provided.

Headers

​
x-shop-id
string

Optional identifier that scopes responses to a specific storefront when the referer cannot be inferred.

Body

application/json
​
code
string
required

Coupon code to verify (case-insensitive).

Example:

"SUMMER20"

​
orderId
string

Optional order ID to validate coupon against order total.

Example:

"67890abcdef1234567890abc"

Response

Coupon is valid.

​
status
integer
required
Example:

200

​
success
boolean
required
Example:

true

​
message
string
required
Example:

"Coupon is valid"

​
data
object
required