API Reference
Promo code validation
Publicly validate a promotional code for a plan.
POST /api/referral/promo-codes/validateAccess: Public
Request body
{
"code": "WELCOME10",
"planId": "plan_uuid",
"companyRef": "readyzone-center-12345"
}code and planId are required. companyRef is recommended when the code is entered from a zone portal.
| Attribute | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Promotional code entered by the customer. |
planId | string (UUID) | Yes | Target plan. |
companyId | string (UUID) | No | Internal zone identifier. |
companyRef | string | No | Public zone reference. |
beneficiaryUserId | string (UUID) | No | Beneficiary, used for example to prevent self-use. |
Response
The response indicates whether the code is valid and returns the discount information applicable to the plan.
The portal must treat the response as the eligibility decision and must not calculate the discounted amount itself.
Status codes
- 200 OK
- 400 Bad Request (invalid code or plan)
- 404 Not Found (code not found)
- 422 Unprocessable Entity (expired, exhausted, or inapplicable code)