Skip to main content

Validation

Overview​

The /api/v1/promo-codes endpoint allows third-party applications to validate promo codes for a specific organization and product bundle. This endpoint checks both global promo codes and organization-specific promo codes to determine validity and return discount information.

Base URLs​

  • Production: https://api.care360-next.carevalidate.com/api/v1/promo-codes
  • Staging: https://api-staging.care360-next.carevalidate.com/api/v1/promo-codes

Method: GET

Authentication​

Required Headers​

cv-api-key: your-secret-api-key

The cv-api-key is your organization's secret API key provided by CareValidate.

Query Parameters​

ParameterTypeRequiredDescription
codestringYesThe promo code to validate
product_bundle_idstring (UUID)NoUUID of the product bundle to validate against

Request Examples​

Basic Promo Code Validation​

GET /api/v1/promo-codes?code=PER10

Promo Code Validation with Product Bundle​

GET /api/v1/promo-codes?code=PER10&product_bundle_id=0aad00c1-9c18-4b7c-ac3c-67afffdfbc4e

Response Format​

Success Response (Valid Promo Code)​

HTTP Status: 200 OK

{
  "success": true,
  "data": [
    {
      "flatDiscount": 10.00
    }
  ]
}
{
  "success": true,
  "data": [
    {
      "percentDiscount": 15
    }
  ]
}

Response Fields​

FieldTypeDescription
successbooleanIndicates if the promo code is valid
dataarrayArray containing discount information (empty if invalid)
data[].flatDiscountnumberFixed discount amount in dollars (mutually exclusive with percentDiscount)
data[].percentDiscountnumberPercentage discount (0-100, mutually exclusive with flatDiscount)

Note: Each promo code will have either a flatDiscount OR a percentDiscount, never both. If the promo code is invalid, the data array will be empty.

cURL Examples​

Validate Promo Code Only​

curl -X GET "https://api.care360-next.carevalidate.com/api/v1/promo-codes?code=PER10" \
  -H "cv-api-key: YOUR_SECRET_KEY_HERE"

Validate Promo Code with Product Bundle​

curl -X GET "https://api.care360-next.carevalidate.com/api/v1/promo-codes?code=PER10&product_bundle_id=0aad00c1-9c18-4b7c-ac3c-67afffdfbc4e" \
  -H "cv-api-key: YOUR_SECRET_KEY_HERE"

Error Responses​

Promocode not found​

HTTP Status: 404 Not Found

{
  "success": false,
  "message": "Promo code not found!"
}

Missing Required Parameters​

HTTP Status: 400 Bad Request

{
  "success": false,
  "message": "Promo code is required"
}

Invalid Product Bundle ID​

HTTP Status: 400 Bad Request

{
  "success": false,
  "message": "Invalid product bundle ID format"
}

Authentication Errors​

HTTP Status: 401 Unauthorized

{
  "status": 401,
  "error": "Invalid API key"
}

Internal Server Error​

HTTP Status: 500 Internal Server Error

{
  "success": false,
  "message": "Internal server error"
}

Changelog​

VersionDateChanges
1.02025-09-16Initial Promo Code Validation API documentation