Skip to main content
POST
/
coupons
/
apply-coupon
curl -X POST https://api.example.com/coupons/apply-coupon \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SUMMER2026"
  }'

{
  "message": "Coupon applied successfully",
  "id": 1,
  "name": "SUMMER2026",
  "percentage": 25,
  "expirationDate": "2026-08-31"
}
This endpoint is publicly accessible and does not require admin authentication. Any authenticated user can apply coupons.

​
Request Body

​
name
string
required
The coupon code/name to apply

​
Response

Returns a success message along with the coupon details if valid and not expired.
​
message
string
Confirmation message indicating successful coupon application
​
id
number
The unique identifier for the coupon
​
name
string
The coupon name/code
​
percentage
number
The discount percentage to apply (1-100)
​
expirationDate
string
The expiration date of the coupon
curl -X POST https://api.example.com/coupons/apply-coupon \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SUMMER2026"
  }'

{
  "message": "Coupon applied successfully",
  "id": 1,
  "name": "SUMMER2026",
  "percentage": 25,
  "expirationDate": "2026-08-31"
}

​
Validation

The endpoint performs the following validations:
  1. Coupon Existence: Verifies that a coupon with the provided name exists
  2. Expiration Check: Validates that the current date is before or on the coupon’s expiration date (end of day)

​
Expiration Logic

The expiration validation uses endOfDay() for the coupon’s expiration date, meaning:
  • A coupon with expiration date “2026-08-31” is valid throughout the entire day (until 23:59:59)
  • The coupon expires after midnight on the expiration date

​
Use Cases

  • Apply discount codes during checkout
  • Validate promotional codes before processing orders
  • Show users the discount percentage they’ll receive
  • Provide real-time feedback on coupon validity

​
Error Handling

The coupon code does not exist in the system. This could mean:
  • The code was typed incorrectly
  • The coupon has been deleted
  • The code has never been created
The coupon exists but has expired. The expiration date has passed, and the coupon can no longer be used.
The request validation failed. The coupon name/code was not provided in the request body.

Build docs developers (and LLMs) love

Get started for freeTalk to us