Cancel flows

What the flow asks and offers lives in the dashboard, so you can change it without a deploy. Your code adds a button and a dialog, and your server mints a short-lived token for the signed-in account. Set up the steps, questions and save offers in Dashboard: Cancel flows.

The SDK lives in offer-app/src/sdk/cancel. The dashboard imports it as @/sdk/cancel; in your app, map @offer/sdk/cancel to it as shown in Access and entitlements.

Add a cancel button#

1. Activate a flow#

   Create a flow in the dashboard and set it to active. Without a flow prop, the SDK runs the app's active flow, preferring the one with id default. Account tokens can only start active flows.

2. Mint an account token on your server#

   Call POST /apps/:appId/namespaces/:accountId/token with the secret key. The token can act for that one account and nothing else, so it is safe in the browser. The publishable key can't start a cancel flow.

   curl -X POST http://localhost:6767/apps/$APP_ID/namespaces/user_42/token \
     -H "Authorization: Bearer $OFFER_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "ttl_seconds": 3600 }'

   201 Created

   {
     "account_id": "user_42",
     "token": "act_eyJhIjoiYXBwX0FiQ2RFZiIsIm4iOiJ1c2VyXzQyIiwiZSI6MTc5MDg1OTYwMH0.Xk2…",
     "expires_at": "2026-10-01T13:00:00.000Z"
   }

3. Render the provider#

   Pass the token to a client component. CancelFlow.Trigger opens the flow and CancelFlow.Dialog shows it in a modal <dialog>.

   app/account/page.tsx

   // app/account/page.tsx
   import { OfferClient } from "@offer/sdk";
   import { requireUser } from "@/lib/session"; // your own auth helper
   import { CancelButton } from "./cancel-button";
   
   const offer = new OfferClient({ baseUrl: process.env.OFFER_API_URL, apiKey: process.env.OFFER_SECRET_KEY });
   
   export default async function AccountPage() {
     const user = await requireUser();
     const appId = process.env.OFFER_APP_ID!;
   
     // Minted on every render with the secret key. Only the token reaches the browser.
     const { token } = await offer.request<{ token: string; expires_at: string }>(
       `/apps/${appId}/namespaces/${encodeURIComponent(user.id)}/token`,
       { method: "POST", body: JSON.stringify({ ttl_seconds: 3600 }) },
     );
   
     return <CancelButton apiUrl={process.env.OFFER_API_URL!} appId={appId} token={token} />;
   }

   app/account/cancel-button.tsx

   // app/account/cancel-button.tsx
   "use client";
   
   import { CancelFlow, CancelFlowProvider } from "@offer/sdk/cancel";
   import { useRouter } from "next/navigation";
   
   export function CancelButton(props: { apiUrl: string; appId: string; token: string }) {
     const router = useRouter();
     return (
       <CancelFlowProvider {...props} onSaved={() => router.refresh()} onCancelled={() => router.refresh()}>
         <CancelFlow.Trigger className="link-danger">Cancel subscription</CancelFlow.Trigger>
         <CancelFlow.Dialog className="cancel-dialog" />
       </CancelFlowProvider>
     );
   }

The dashboard's /demo/account page is this pattern end to end, with the token minted on the server and the flow styled as a sample app.

Account tokens#

The provider doesn't refresh tokens. Mint one when you render the page, with a lifetime longer than a visit. A session from another account answers 404, so a token can't find out that other sessions exist.

CancelFlowProvider#

Components#

CancelFlow.* components render plain, unstyled markup with data-* attributes for state, and take className. CancelFlow.Dialog renders CancelFlow.Steps when you give it no children. Pass children to lay out the pieces yourself.

Question, Text, Offer, Confirm and Done also take a function as children with the step (or offer, or session) and the full context. offerSummary(offer) turns an offer's numbers into one line, such as “$34.30/month for 3 months, then $49”.

// import { CancelFlow, offerSummary } from "@offer/sdk/cancel";
<CancelFlow.Dialog className="cancel-dialog">
  <CancelFlow.Close />
  <CancelFlow.Question />
  <CancelFlow.Text />
  <CancelFlow.Offer>
    {(offer, step, { accept, decline, phase }) => (
      <div className="save-offer" data-kind={offer.kind}>
        <h2>{offer.headline}</h2>
        <p>{offer.body}</p>
        <p>{offerSummary(offer)}</p>
        <button type="button" disabled={phase !== "ready"} onClick={() => void accept()}>{offer.cta}</button>
        <button type="button" onClick={() => void decline()}>{step.decline_label ?? "No thanks"}</button>
      </div>
    )}
  </CancelFlow.Offer>
  <CancelFlow.Confirm />
  <CancelFlow.Done />
  <CancelFlow.Error />
</CancelFlow.Dialog>

useCancelFlow()#

Returns the provider's state for a fully custom UI: isOpen, phase, session, step, offer, error, the current choice and text, and the actions open, close, choose, setText, submit, back, accept, decline and confirmCancel.

Steps and sessions#

Each click is one API call, and each call returns the session as the customer should see it. A flow has four kinds of step: question, text, offer and confirm. Answers can branch to different steps. When the customer reaches the offer step, the API works out the offer for their answers. If no offer applies to this account, the step is skipped.

{
  "id": "cxl_Q2wErTyUiOpAsDfG",
  "status": "open",
  "flow": { "id": "default", "name": "Cancel flow" },
  "step": { "id": "offer", "type": "offer", "title": "Before you go", "decline_label": null },
  "progress": { "index": 1, "total": 3 },
  "can_go_back": true,
  "offer": {
    "kind": "discount",
    "source": "dynamic",
    "details": { "percent": 30, "cycles": 3, "price": 34.3, "regular_price": 49, "currency": "USD", "interval": "month" },
    "headline": "Stay for 30% less",
    "body": "Keep everything you've built for $34.30/month for the next 3 months.",
    "cta": "Keep my plan for less",
    "status": "shown"
  },
  "approve_url": null,
  "result": null,
  "account": {
    "id": "user_42",
    "plan_name": "Pro",
    "subscription": { "price": 49, "currency": "USD", "interval": "month", "renews_at": "2026-11-01T12:00:00.000Z" }
  }
}

source: "dynamic" means the agent picked the offer for this customer, within the guardrails set on the flow. That needs ANTHROPIC_API_KEY on the API and dynamic offers turned on for the step. Otherwise the flow shows its static offer for the answers given.

Outcomes#

Accepting the offer ends the session as saved. What happens to the subscription depends on the offer's kind.

For discounts and downgrades, the session comes back with approve_url. The provider opens it according to the paypal prop, and PayPal sends the customer back to returnUrl.

The API sends cancel_flow.saved or cancel_flow.cancelled with the session, the answers and the offer. Pauses also send subscription.paused, and later subscription.resumed. See Webhooks.

The transport prop#

The provider talks to the API through a CancelTransport. By default it builds a CancelClient from apiUrl, appId and token. Pass your own to wrap the client, or to run the flow without the API.

export interface CancelTransport {
  start(flow?: string | null): Promise<CancelSession>;
  answer(sessionId: string, body: { step: string; answer?: string | null; text?: string | null }): Promise<CancelSession>;
  back(sessionId: string): Promise<CancelSession>;
  decline(sessionId: string): Promise<CancelSession>;
  accept(sessionId: string, urls?: { return_url?: string; cancel_url?: string }): Promise<CancelSession>;
  cancel(sessionId: string): Promise<CancelSession>;
  close(sessionId: string): Promise<CancelSession>;
}

import { CancelClient, CancelFlow, CancelFlowProvider, type CancelTransport } from "@offer/sdk/cancel";

// Logs every step, then calls the API as usual.
function loggingTransport(inner: CancelTransport): CancelTransport {
  return {
    start: (flow) => inner.start(flow),
    answer: (id, body) => {
      analytics.track("cancel_flow_answer", body);
      return inner.answer(id, body);
    },
    back: (id) => inner.back(id),
    decline: (id) => inner.decline(id),
    accept: (id, urls) => inner.accept(id, urls),
    cancel: (id) => inner.cancel(id),
    close: (id) => inner.close(id),
  };
}

const transport = loggingTransport(new CancelClient({ apiUrl, appId, token }));

<CancelFlowProvider transport={transport}>
  <CancelFlow.Trigger />
  <CancelFlow.Dialog />
</CancelFlowProvider>

The dashboard's live preview uses a transport that walks unsaved steps in the browser and asks the API only for the offer. Nothing is saved and nobody is charged. It passes paypal="manual" so accepting an offer never leaves the page.

Without React#

The flow is plain HTTP, so your server or another frontend can drive it with an account token, or with the secret key and an account in the start body.

A call that doesn't fit the current step returns 409. With the secret key, GET /apps/:appId/cancel-sessions lists recent sessions with every answer and why the offer was chosen.