Validation

GET/api/v1/promo-codes

Validates a promo code and returns its discount details. Checks both global and organization-specific promo codes, optionally scoped to a product bundle.

cv-api-key

Productionhttps://api.care360-next.carevalidate.com/api/v1/promo-codes

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/promo-codes

Parameters

Headers

cv-api-keystringrequired

Your organization's secret API key provided by CareValidate

Query Parameters

codestringrequired

The promo code to validate

Example: PER10

product_bundle_idstring (UUID)optional

UUID of the product bundle to validate against

Example: 0aad00c1-9c18-4b7c-ac3c-67afffdfbc4e

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.

Response Fields

Response Body

successbooleanoptional

Indicates if the promo code is valid

dataarrayoptional

Array containing discount information (empty if invalid)

Show 2 child properties

flatDiscountnumberoptional

Fixed discount amount in dollars (mutually exclusive with percentDiscount)

percentDiscountnumberoptional

Percentage discount 0-100 (mutually exclusive with flatDiscount)

---

Changelog

Version	Date	Changes
1.0	2025-09-16	Initial Promo Code Validation API documentation

Examples

cURL (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"

cURL (with 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"

JavaScript

const params = new URLSearchParams({
code: "PER10",
product_bundle_id: "0aad00c1-9c18-4b7c-ac3c-67afffdfbc4e",
});

const response = await fetch(
`https://api.care360-next.carevalidate.com/api/v1/promo-codes?${params}`,
{
  method: "GET",
  headers: {
    "cv-api-key": "YOUR_SECRET_KEY_HERE",
  },
}
);

const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
  "https://api.care360-next.carevalidate.com/api/v1/promo-codes",
  headers={
      "cv-api-key": "YOUR_SECRET_KEY_HERE",
  },
  params={
      "code": "PER10",
      "product_bundle_id": "0aad00c1-9c18-4b7c-ac3c-67afffdfbc4e",
  },
)

print(response.json())

Responses

▶200Valid (Flat Discount)Promo code is valid and returns a flat dollar discount.

{
  "success": true,
  "data": [
    {
      "flatDiscount": 10
    }
  ]
}

▶200Valid (Percent Discount)Promo code is valid and returns a percentage discount.

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

▶400Missing Required ParametersReturned when the code query parameter is missing.

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

▶400Invalid Product Bundle IDReturned when the product_bundle_id is not a valid format.

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

▶401UnauthorizedReturned when the API key is missing or invalid.

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

▶404Not FoundReturned when the promo code does not exist.

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

▶500Internal Server ErrorReturned when an unexpected error occurs.

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

Try It Out

Try itAPI Playground

▶