Entitlement ops

These endpoints mirror the entitlement actions in Admin → Contacts. All require the manage scope, a location_id in the JSON body, and a request_id for idempotency. The path :id is the internal entitlement UUID (returned by grants and deduct responses, or visible in admin).

Pause

POST /api/v2/entitlements/:id/pause

Pauses an entitlement until paused_until. Only works when pause is enabled in location settings.

Request body

Field	Type	Required	Notes
`location_id`	string	yes	Must match the token’s location
`request_id`	string	yes	Idempotency key
`paused_until`	string	yes	ISO 8601 datetime in the future

curl

curl -X POST https://app.<your-domain>/api/v2/entitlements/kotally-entitlement-uuid/pause \
  -H "Authorization: Bearer ktly_<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "location_id": "loc_1",
        "request_id": "pause-ent-123",
        "paused_until": "2026-06-01T00:00:00.000Z"
      }'

Unpause

POST /api/v2/entitlements/:id/unpause

Clears the pause on an entitlement and returns it to active status.

Request body

Field	Type	Required	Notes
`location_id`	string	yes	Must match the token’s location
`request_id`	string	yes	Idempotency key

curl

curl -X POST https://app.<your-domain>/api/v2/entitlements/kotally-entitlement-uuid/unpause \
  -H "Authorization: Bearer ktly_<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "location_id": "loc_1",
        "request_id": "unpause-ent-123"
      }'

Adjust credits

POST /api/v2/entitlements/:id/adjust

Adds or removes credits manually. Same rules as admin — a negative delta cannot bring the balance below zero.

Request body

Field	Type	Required	Notes
`location_id`	string	yes	Must match the token’s location
`request_id`	string	yes	Idempotency key
`delta`	integer	yes	Non-zero integer; positive adds credits, negative removes
`note`	string	yes	Non-empty reason for the adjustment (stored in the ledger)

curl

curl -X POST https://app.<your-domain>/api/v2/entitlements/kotally-entitlement-uuid/adjust \
  -H "Authorization: Bearer ktly_<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "location_id": "loc_1",
        "request_id": "adjust-ent-123",
        "delta": 2,
        "note": "Comp class for missed session"
      }'

Extend expiry

POST /api/v2/entitlements/:id/extend-expiry

Extends the expiry date on a package entitlement. Provide exactly one of extends_to or extend_days. Membership entitlements cannot be extended.

Request body

Field	Type	Required	Notes
`location_id`	string	yes	Must match the token’s location
`request_id`	string	yes	Idempotency key
`extends_to`	string	one of†	ISO 8601 datetime in the future — sets expiry to this date
`extend_days`	integer	one of†	Positive integer — adds this many days to the current expiry

† Provide exactly one of extends_to or extend_days.

curl

curl -X POST https://app.<your-domain>/api/v2/entitlements/kotally-entitlement-uuid/extend-expiry \
  -H "Authorization: Bearer ktly_<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "location_id": "loc_1",
        "request_id": "extend-ent-123",
        "extend_days": 14
      }'

Response (200)

All four endpoints return the same shape on success:

{
  "ok": true,
  "reason_code": "entitlement_paused",
  "correlation_id": "a1b2c3d4-...",
  "entitlement": {
    "id": "kotally-entitlement-uuid",
    "contact_id": "contact-uuid",
    "product_config_id": "pc_package_1",
    "status": "paused",
    "credits_remaining": 4,
    "expires_at": "2026-06-15T00:00:00.000Z",
    "paused_until": "2026-06-01T00:00:00.000Z",
    "updated_at": "2026-05-01T12:00:00.000Z"
  }
}

Success reason_code values: entitlement_paused, entitlement_unpaused, entitlement_adjusted, entitlement_expiry_extended.

Errors

Status	When
`400`	Validation error (missing field, invalid `delta`, membership extend rejected, pause disabled)
`403`	`BILLING_SUSPENDED` — workspace billing is suspended
`404`	Entitlement not found for this location

See the Overview for the full error model.