Skip to main content

​
Get Active Coupons

Retrieve all currently active coupons. This is a public endpoint used for displaying available promotions.

​
Authentication

Not required. This is a public endpoint.

​
Response

​
coupons
array
required
Array of active coupon objects
​
coupons[]._id
string
Coupon identifier
​
coupons[].code
string
Coupon code to use at checkout
​
coupons[].discountType
string
Type of discount: “percentage” or “fixed”
​
coupons[].discountValue
number
Discount value (1-100 for percentage, Colombian pesos for fixed)
​
coupons[].expiresAt
string
ISO 8601 expiration date (null if no expiration)
​
coupons[].isActive
boolean
Always true for this endpoint

​
Example Request

curl -X GET https://api.donpalitojr.com/api/coupons/active

​
Example Response

{
  "coupons": [
    {
      "_id": "65f8a1b2c3d4e5f6g7h8i9j0",
      "code": "WELCOME10",
      "discountType": "percentage",
      "discountValue": 10,
      "expiresAt": "2024-12-31T23:59:59.000Z",
      "isActive": true
    },
    {
      "_id": "65f8a1b2c3d4e5f6g7h8i9j1",
      "code": "FREESHIP",
      "discountType": "fixed",
      "discountValue": 5000,
      "expiresAt": null,
      "isActive": true
    }
  ]
}
Active coupons are those that are:
  • Marked as isActive: true
  • Not expired (or have no expiration date)
This endpoint is commonly used for homepage marquees or promotional banners.

​
Validate Coupon

Validate a coupon code and calculate the discount for a given cart total.

​
Authentication

Required. User must be authenticated via Clerk.

​
Request Body

​
code
string
required
The coupon code to validate (case-insensitive)
​
cartTotal
number
required
The current cart total in Colombian pesos (COP)

​
Response

​
isValid
boolean
required
Whether the coupon is valid for use
​
discountAmount
number
The discount amount in COP (only present if valid)
​
finalTotal
number
The final total after applying the discount (only present if valid)
​
coupon
object
The coupon object (only present if valid)
​
coupon._id
string
Coupon identifier
​
coupon.code
string
Coupon code
​
coupon.discountType
string
“percentage” or “fixed”
​
coupon.discountValue
number
Discount value
​
message
string
Error message (only present if invalid)

​
Example Request

curl -X POST https://api.donpalitojr.com/api/coupons/validate \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "cartTotal": 100000
  }'

​
Example Response (Valid)

{
  "isValid": true,
  "discountAmount": 10000,
  "finalTotal": 90000,
  "coupon": {
    "_id": "65f8a1b2c3d4e5f6g7h8i9j0",
    "code": "WELCOME10",
    "discountType": "percentage",
    "discountValue": 10
  }
}

​
Example Response (Invalid)

{
  "isValid": false,
  "message": "Coupon code not found or expired"
}

​
Validation Rules

The coupon validation checks for:
  1. Coupon exists - The code must match an existing coupon
  2. Active status - Coupon must be marked as isActive: true
  3. Not expired - Current date must be before expiresAt (if set)
  4. One-time use - User must not have already used this coupon (checked via usedBy array)
  • "Coupon code not found or expired" - Code doesn’t exist, is inactive, or has expired
  • "You have already used this coupon" - User has already redeemed this coupon previously
  • "Coupon is not active" - Coupon is disabled by admin

​
Applying Coupons

Coupons can be applied during the checkout process when creating a payment intent: 
curl -X POST https://api.donpalitojr.com/api/payment/create-intent \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cartItems": [...],
    "shippingAddress": {...},
    "couponCode": "WELCOME10"
  }'
The payment intent endpoint will:
  1. Validate the coupon
  2. Calculate the discount
  3. Apply it to the total
  4. Mark the coupon as used by adding the user to the usedBy array
See the Payment API documentation for more details.

​
Error Responses

​
error
string
Error message describing what went wrong

​
Common Error Codes

  • 400 - Bad Request (missing code or cartTotal)
  • 401 - Unauthorized (authentication required for validate endpoint)
  • 404 - Not Found (coupon doesn’t exist)
  • 500 - Internal Server Error

​
Example Error Response

{
  "error": "Code and cartTotal are required"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us