RetentBase API integration guide

Hosted flow: complete implementation

In this model, your backend calls RetentBase once to create a hosted cancellation link, then redirects the customer. RetentBase never changes billing directly.

Required (2 steps)

Create link via POST /api/v1/cancel-link.
Redirect the user to the returned url.

This is all you need on the Core plan. Hosted flow works without any Advanced fields.

Optional but recommended: verify ci_result_token before changing billing state. The token is returned in the URL hash fragment (#ci_result_token=...).

Advanced only: you can optionally send context.mrr and context.tenure for segmentation. If omitted, hosted flow still works normally.

Final schema: userId, context, metadata, and environment. On the Core plan, context.mrr and context.tenureDays can be omitted.

Step 1: Create cancel link from your backend

POST /api/v1/cancel-link

const response = await fetch("https://api.retentbase.com/api/v1/cancel-link", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer " + process.env.RETENTBASE_API_KEY,
  },
  body: JSON.stringify({
    userId: "user_123",
    returnUrl: "https://app.example.com/billing/cancel/callback",
    environment: "prod",
    context: {
      plan: "pro_monthly",
      // Advanced only:
      mrr: 129,
      tenureDays: 42,
    },
    metadata: {
      source: "billing_settings_page",
    },
  }),
});

if (!response.ok) throw new Error("cancel-link failed");
const payload = await response.json();
// payload.url, payload.expiresAt, payload.environment, payload.sessionId

Step 2: Redirect user to hosted page

Redirect

return Response.redirect(payload.url, 302);

Optional step: Verify result token before billing action

Verify ci_result_token

// 1) In your callback page (client-side), read token from URL fragment.
const token = new URLSearchParams(window.location.hash.replace(/^#/, "")).get("ci_result_token");
if (!token) throw new Error("Missing ci_result_token");

// 2) Send token to your backend so billing actions stay server-side.
const res = await fetch("/api/billing/cancel-callback", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token }),
});
if (!res.ok) throw new Error("Callback processing failed");

POST/api/v1/cancel-link

Creates a hosted-flow URL with a short-lived token and a session_id for diagnostics.

Notes

Use user_id as your stable customer reference.
Use context only for analytics enrichment; the hosted flow works without MRR or tenure.

Availability

Core and Advanced plans

Auth

Authorization: Bearer <Workspace API Key> or x-api-key

Content-Type

application/json

JSON Body

Field	Type	Required	Description
userId	string	Yes	Your stable user identifier.
returnUrl	string(url)	No	Override callback URL. Must be allowlisted.
environment	"prod" \| "sandbox"	No	Environment for the hosted session.
context.plan	string	No	Customer plan label for analytics context.
context.mrr	number	No	Optional (Advanced): monthly recurring revenue for segmentation cohorts.
context.tenureDays	integer	No	Optional (Advanced): customer tenure in days for lifecycle cohorts.
metadata	object	No	Optional flat object (string/number/boolean/null values).

Success Responses

Status	Meaning
200	Returns hosted URL, expires_at, environment and session_id.

Error Responses

Status	Meaning
400	Invalid body or return_url not allowlisted.
401	Missing/invalid API key.
402	Workspace is read-only due to expired subscription access.
403	Forbidden: this endpoint is unavailable for the current workspace or plan.
409	Default return URL is not configured.
415	Content-Type must be application/json.
429	Rate limit exceeded.

Optional hardening endpoints

POST/api/public/cancel/result

Optional: verifies the signed hosted-flow result token and returns the trusted outcome payload.

Availability

Optional hardening (Core and Advanced plans)

Auth

No API key. Token signature validation is required.

JSON Body

Field	Type	Required	Description
token	string	Yes	The ci_result_token received in your callback URL hash fragment.

Success Responses

Status	Meaning
200	Token valid and result payload returned.

Error Responses

Status	Meaning
400	Missing or malformed token.
401	Expired token.

GET/api/v1/cancel-sessions/{session_id}

Returns hosted-session diagnostics (session state, linked event, completion status).

Availability

Advanced plan only

Auth

Authorization: Bearer <Workspace API Key> or x-api-key

Path Parameters

Field	Type	Required	Description
session_id	string(uuid)	Yes	The session_id from cancel-link response or rb_session callback param.

Success Responses

Status	Meaning
200	Session status returned.

Error Responses

Status	Meaning
400	Missing session_id.
401	Missing or invalid API key.
403	Forbidden: this endpoint is unavailable for the current workspace or plan.
404	Session not found for this workspace.
429	Rate limit exceeded.

RetentBase API integration guide

Before you start

Choose integration model

Hosted flow: complete implementation

Implementation checklist