Check eligibility

POST /api/v2/entitlements/check-eligibility

Checks whether a contact has enough credits to proceed. Does not modify any balance — use it before confirming a booking. Requires the check scope.

Request body

Field	Type	Required	Notes
location_id	string	yes	Must match the token’s location
external_contact_id	string	yes†	Provider-neutral contact id. Send this or ghl_contact_id — interchangeable; must match the id used on the grant
ghl_contact_id	string	yes†	The GoHighLevel contact id. Interchangeable with external_contact_id
product_config_id	string	yes*	The product config to check against
calendar_id	string	yes*	Alternative to product_config_id
amount	integer	no	Credits to check; defaults to 1

* Either product_config_id or calendar_id is required.
† Exactly one of external_contact_id or ghl_contact_id is required.

curl

curl -X POST https://app.<your-domain>/api/v2/entitlements/check-eligibility \
  -H "Authorization: Bearer ktly_<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "location_id": "loc_1",
        "ghl_contact_id": "ghl_contact_123",
        "product_config_id": "pc_package_1",
        "amount": 1
      }'

JavaScript

const res = await fetch(
  "https://app.<your-domain>/api/v2/entitlements/check-eligibility",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KOTALLY_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      location_id: "loc_1",
      ghl_contact_id: "ghl_contact_123",
      product_config_id: "pc_package_1",
      amount: 1,
    }),
  },
);
const data = await res.json();
// data.ok === true  -> eligible

Response (200)

{
  "ok": true,
  "reason_code": "eligible",
  "correlation_id": "a1b2c3d4-...",
  "balance_after": 9
}

• balance_after — the balance the contact would have if the matching amount were deducted. No credits are actually moved.

Failure reason codes

reason_code	Meaning
NO_ENTITLEMENT	Contact has no matching entitlement
INSUFFICIENT_CREDITS	Contact does not have enough credits

See the Overview for HTTP status codes and the full reason-code list.