Validate Promo Code

Check if a promo code is valid and calculate the discount amount.

Endpoint

POST /v1/promo-codes/validate

Request Body

Field	Type	Required	Description
code	string	Yes	Promo code to validate
customer_id	integer	No	Customer ID (for per-customer limits)
products	array	No	Products in the booking
products[].id	integer	Yes*	Product ID
products[].category_id	integer	No	Product category ID
products[].price	number	Yes*	Product price
products[].name	string	No	Product name
experiences	array	No	Experiences in the booking
experiences[].id	integer	Yes*	Experience ID
experiences[].category_id	integer	No	Experience category ID
experiences[].price	number	Yes*	Experience price
experiences[].name	string	No	Experience name
subtotal	number	No	Total booking subtotal

Example Request

curl -X POST "https://app.equipdash.com/api/v1/promo-codes/validate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER10",
    "customer_id": 456,
    "products": [
      {
        "id": 1,
        "category_id": 5,
        "price": 100.00,
        "name": "Mountain Bike"
      },
      {
        "id": 2,
        "price": 50.00,
        "name": "Helmet"
      }
    ],
    "subtotal": 150.00
  }'

Success Response

{
  "data": {
    "valid": true,
    "promo_code": {
      "id": 1,
      "code": "SUMMER10",
      "name": "Summer Sale 10% Off",
      "discount_type": "percentage",
      "discount_value": 10.00
    },
    "discount_amount": 15.00,
    "eligible_items": ["Mountain Bike", "Helmet"]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T10:00:00+00:00"
  }
}

Error Response

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": [
      {
        "field": "code",
        "message": "This promo code has expired."
      }
    ]
  }
}

Possible Validation Errors

Error	Description
Invalid promo code	Code doesn't exist
This promo code is no longer active	Status is not active
This promo code is not yet valid	valid_from is in the future
This promo code has expired	valid_until is in the past
This promo code has reached its usage limit	max_uses exceeded
You have already used this promo code the maximum number of times	max_uses_per_customer exceeded
This promo code doesn't apply to any items in your booking	No eligible items
Minimum booking amount of X not met	min_booking_amount not reached

Notes

• Validation is read-only - it doesn't consume the promo code
• Provide products/experiences for accurate discount calculation
• The eligible_items array shows which items qualify for the discount