Update Case Promo Code

POST/api/v1/cases/:caseId

Sets, replaces, or clears the promo code attached to an existing case. Uses the UPDATE_CASE_PROMO_CODE action of the case actions endpoint.

cv-api-key

Productionhttps://api.care360-next.carevalidate.com/api/v1/cases/:caseId

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/cases/:caseId

Parameters

Headers

cv-api-keystringrequired

Your organization's secret API key provided by CareValidate

Content-Typestringrequired

Must be application/json.

Example: application/json

Path Parameters

caseIdstring (UUID)required

Unique identifier of the case. The case must belong to your organization.

Example: ec5e0d29-bf87-46b9-98e7-03848442fe53

Request Body

actionstringrequired

Must be exactly `UPDATE_CASE_PROMO_CODE`

Values:UPDATE_CASE_PROMO_CODE

promoCodestring | nullrequired

The promo code to attach to the case, replacing any code already attached. Send `null` to remove the attached promo code. The field is required: omitting it is rejected rather than treated as a removal. No other fields are accepted.

Example: SAVE10

How it works

• The code is matched on its value, ignoring letter case, the same way payment.promoCode is resolved when a case is created. The promo code must be enabled, available for payments, and either belong to your organization or be global. A promo code name that differs from its value is not accepted.
• This endpoint only attaches the code to the case. It does not calculate a discount and never changes an existing payment, whatever its status. Paid payments and preauthorization holds keep their amount, discount, and promo code.
• The new code applies to later payments. Payments created afterwards with applyPromoCode: true use the code currently attached to the case. See Create Case Payment and Add Case Products.
• Changes are recorded in the case activity (for example changed promo code from SAVE10 to SAVE20). Sending the code that is already attached, or sending null when none is attached, succeeds and changes nothing.
• Nothing changes on error. An unknown, disabled, non-payment, or other-organization promo code returns a 400 and leaves the case's promo code as it was.

---

Changelog

Version	Date	Changes
1.0	2026-10-22	Initial Update Case Promo Code documentation

Examples

cURL (Set / Replace)

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/cases/ec5e0d29-bf87-46b9-98e7-03848442fe53" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
  "action": "UPDATE_CASE_PROMO_CODE",
  "promoCode": "SAVE10"
}'

cURL (Remove)

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/cases/ec5e0d29-bf87-46b9-98e7-03848442fe53" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
  "action": "UPDATE_CASE_PROMO_CODE",
  "promoCode": null
}'

JavaScript

const caseId = "ec5e0d29-bf87-46b9-98e7-03848442fe53";

const response = await fetch(
`https://api.care360-next.carevalidate.com/api/v1/cases/${caseId}`,
{
  method: "POST",
  headers: {
    "cv-api-key": "YOUR_SECRET_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action: "UPDATE_CASE_PROMO_CODE",
    promoCode: "SAVE10", // use null to remove the promo code
  }),
}
);

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

Python

import requests

case_id = "ec5e0d29-bf87-46b9-98e7-03848442fe53"

response = requests.post(
  f"https://api.care360-next.carevalidate.com/api/v1/cases/{case_id}",
  headers={
      "cv-api-key": "YOUR_SECRET_KEY_HERE",
      "Content-Type": "application/json",
  },
  json={
      "action": "UPDATE_CASE_PROMO_CODE",
      "promoCode": "SAVE10",  # use None to remove the promo code
  },
)

print(response.json())

Responses

▶200Promo Code UpdatedThe promo code is now attached to the case. The same response is returned when the code was already attached.

{
  "status": 200,
  "success": true,
  "message": "Case promo code updated successfully",
  "data": {
    "caseId": "ec5e0d29-bf87-46b9-98e7-03848442fe53",
    "promoCode": {
      "name": "Summer Sale",
      "value": "SAVE10"
    }
  }
}

▶200Promo Code RemovedReturned when `promoCode` is `null`. The case has no promo code attached afterwards.

{
  "status": 200,
  "success": true,
  "message": "Case promo code removed successfully",
  "data": {
    "caseId": "ec5e0d29-bf87-46b9-98e7-03848442fe53",
    "promoCode": null
  }
}

▶400Promo Code Not FoundReturned when the code does not exist, is disabled, is not available for payments, or belongs to another organization. The case is unchanged.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Promo code 'SAVE10' not found or inactive"
}

▶400Validation ErrorReturned when `promoCode` is missing, is an empty string, or is not a string or `null`.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "promoCode, Promo code must be a non-empty string",
  "code": "VALIDATION_ERROR"
}

▶400Case Not FoundReturned when no case exists for the given `caseId`.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "No Case found for provided details!"
}

▶400Missing API KeyReturned when the `cv-api-key` header is missing.

{
  "status": 400,
  "success": false,
  "error": "Missing cv-api-key header",
  "code": "CASE_ERROR"
}

▶401Invalid API KeyReturned when the API key is not valid.

{
  "status": 401,
  "success": false,
  "message": "Permission Denied",
  "error": "Invalid api key",
  "code": "PERMISSION_DENIED_ERROR"
}

▶401Case Belongs To Another OrganizationReturned when the case is not owned by the organization of the API key.

{
  "status": 401,
  "success": false,
  "message": "Permission Denied",
  "error": "Permission denied",
  "code": "PERMISSION_DENIED_ERROR"
}

Try It Out

Try itAPI Playground

▶