Developer API

v1 · Pro and Premium

Use this if you want to build your own cancel UI — in your app's native look, or inside a mobile app — instead of embedding the hosted flow page. Cancel Desk still handles reason storage, offer config, session history and merchant notification; you own the interface.

Authentication

Generate a key from Settings → Developer API in your dashboard (Pro and Premium only). Send it as a Bearer token on every request:

Authorization: Bearer cd_live_xxxxxxxxxxxxxxxxxxxxxxxx

The raw key is shown once, at generation time — only its hash is stored. There is one active key per workspace; regenerating invalidates the old one immediately.

Base URL

https://cancel.klairlabs.com/api/v1/canceldesk

POST/sessions

Start a session against your first flow, or a specific one via slug (from the Flow tab). Returns the flow's current config (reasons, offers, branding) for you to render.

curl -X POST https://cancel.klairlabs.com/api/v1/canceldesk/sessions \
  -H "Authorization: Bearer cd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"custEmail": "customer@example.com"}'

Returns 201 with {ok, sessionId, config, branding}. Past the Free plan's monthly cap, returns {ok:true, sessionId:null, capped:true, config, branding} — render the same flow, just don't expect it recorded to the dashboard.

POST/sessions/{"{id}"}/finish

Submit the outcome once your customer has answered.

curl -X POST https://cancel.klairlabs.com/api/v1/canceldesk/sessions/cs_abc123/finish \
  -H "Authorization: Bearer cd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"outcome": "cancelled", "reason": "too_expensive", "feedback": "great product, just tight on budget"}'

Field	Required	Notes
outcome	Yes	saved_pause, saved_discount, or cancelled
reason	No	One of the reason keys from the session's config
feedback	No	Free text, up to 1000 characters
custEmail	No	If not already set when the session started

This always triggers your configured notification email — the same as the hosted flow — so you're notified to apply an accepted offer or confirm the cancellation on your side.

GET/sessions

List your sessions, most recent first (up to 500). Optional query params: ?slug=<flow>, ?outcome=cancelled.

GET/sessions/{"{id}"}

Fetch a single session by its sessionId.

Errors

Every response is JSON with an ok boolean. On failure, ok:false and an error string. HTTP status codes: 401 (missing/invalid key), 400 (bad input), 404 (not found), 200/201 (success).

Rate limits

The API sits behind the same gateway as the rest of Cancel Desk (50 requests/second burst, 25/second sustained, shared across the account). Need more for a real integration? Email hello@klairtech.com.