Subscription Management Agent

Handle plan upgrades, downgrades, cancellations, billing queries, and payment method updates via web chat or inbound voice — backed by Stripe.

DifficultyIntermediate

TrackDeveloper Track

ChannelsWeb ChatVoice (Inbound)

IntegrationsStripe (subscription management API)Plan/pricing data (knowledge base)Escalation email

What you'll build

An agent that handles the full subscription lifecycle in conversation: plan comparisons, upgrade and downgrade requests, cancellation with a save flow, billing query resolution, and payment method update prompts — all through Stripe, with a human handoff via escalation email for failed payment disputes or multi-month billing discrepancies.

Prerequisites

BimpeAI account with an API key (sk_…)
Read Anatomy of a workflow agent first — this recipe skips steps covered there
Stripe connected in the Console dashboard (see Step 4)
Web chat widget and inbound voice phone number connected in the Console dashboard (see Step 4)
Escalation email configured under Settings → Escalation for billing disputes (see Step 4)

Steps

1. Find the workflow

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

const page = await bimpe.workflows.list({ scope: "public", search: "subscription management" });
const workflow = page.data[0];
console.log(workflow.id, workflow.name);

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

page = client.workflows.list(scope="public", search="subscription management")
workflow = page.data[0]
print(workflow.id, workflow.name)

2. Create the agent

const agent = await bimpe.agents.create(
  {
    name: "Subscription management agent",
    system_prompt:
      "You manage subscription changes for customers. " +
      "For upgrade or downgrade requests: confirm the customer's current plan, show the differences " +
      "and price change from the plan knowledge base, and process the change via the Stripe integration. " +
      "For cancellations: ask the reason, present a save offer from the retention knowledge base, " +
      "and only cancel if the customer declines. Confirm the cancellation date and any remaining access. " +
      "For billing queries: explain the charge from the billing knowledge base. " +
      "For payment method updates: direct the customer to the secure update link from Stripe. " +
      "Escalate failed payment disputes or multi-month discrepancies to the billing team. " +
      "Never quote a price that is not in the plan knowledge base.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-subscription-agent-v1" },
);

console.log(agent.id);

agent = client.agents.create(
    name="Subscription management agent",
    system_prompt=(
        "You manage subscription changes for customers. "
        "For upgrade or downgrade requests: confirm the customer's current plan, show the differences "
        "and price change from the plan knowledge base, and process the change via the Stripe integration. "
        "For cancellations: ask the reason, present a save offer from the retention knowledge base, "
        "and only cancel if the customer declines. Confirm the cancellation date and any remaining access. "
        "For billing queries: explain the charge from the billing knowledge base. "
        "For payment method updates: direct the customer to the secure update link from Stripe. "
        "Escalate failed payment disputes or multi-month discrepancies to the billing team. "
        "Never quote a price that is not in the plan knowledge base."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-subscription-agent-v1",
)

print(agent.id)

3. Add knowledge bases

Three knowledge bases cover plan comparison, billing explanations, and the retention save flow.

// Plan comparison and pricing
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Plan comparison",
  content:
    "Starter — £12/month or £120/year: 1 user, 5 projects, 5 GB storage, email support.\n" +
    "Pro — £39/month or £390/year: 5 users, unlimited projects, 50 GB storage, priority support, API access.\n" +
    "Business — £99/month or £990/year: 20 users, unlimited everything, 500 GB storage, dedicated CSM, SSO.\n" +
    "Enterprise — custom pricing: unlimited users, custom storage, SLA, on-premise option.\n" +
    "Annual billing saves 17% versus monthly. Upgrades are prorated. Downgrades take effect at the next billing cycle.",
});

// Common billing line items
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Billing guide",
  content:
    "Monthly charge: your plan price on the same date each month.\n" +
    "Annual charge: full year billed upfront on the anniversary of signup.\n" +
    "Proration on upgrade: you are charged the difference for the remaining days in the current cycle.\n" +
    "Proration on downgrade: credited amount applied to the next cycle — not refunded immediately.\n" +
    "Failed payment: we retry on days 3, 5, and 7. After the third failure, the account is paused.",
});

// Retention save offers
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Retention offers",
  content:
    "Reason: too expensive → offer 20% off for 3 months (one-time per customer).\n" +
    "Reason: not using it / too busy → offer a 1-month pause at no charge.\n" +
    "Reason: missing a feature → log the feature request and offer a 2-week extension while it is reviewed.\n" +
    "Reason: switching to a competitor → ask what the competitor offers and report back to the product team.\n" +
    "Only one offer per cancellation attempt. Do not stack offers.",
});

# Plan comparison and pricing
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Plan comparison",
    "content": (
        "Starter — £12/month or £120/year: 1 user, 5 projects, 5 GB storage, email support.\n"
        "Pro — £39/month or £390/year: 5 users, unlimited projects, 50 GB storage, priority support, API access.\n"
        "Business — £99/month or £990/year: 20 users, unlimited everything, 500 GB storage, dedicated CSM, SSO.\n"
        "Enterprise — custom pricing: unlimited users, custom storage, SLA, on-premise option.\n"
        "Annual billing saves 17% versus monthly. Upgrades are prorated. Downgrades take effect at the next billing cycle."
    ),
})

# Common billing line items
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Billing guide",
    "content": (
        "Monthly charge: your plan price on the same date each month.\n"
        "Annual charge: full year billed upfront on the anniversary of signup.\n"
        "Proration on upgrade: you are charged the difference for the remaining days in the current cycle.\n"
        "Proration on downgrade: credited amount applied to the next cycle — not refunded immediately.\n"
        "Failed payment: we retry on days 3, 5, and 7. After the third failure, the account is paused."
    ),
})

# Retention save offers
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Retention offers",
    "content": (
        "Reason: too expensive → offer 20% off for 3 months (one-time per customer).\n"
        "Reason: not using it / too busy → offer a 1-month pause at no charge.\n"
        "Reason: missing a feature → log the feature request and offer a 2-week extension while it is reviewed.\n"
        "Reason: switching to a competitor → ask what the competitor offers and report back to the product team.\n"
        "Only one offer per cancellation attempt. Do not stack offers."
    ),
})

4. Connect channels and integrations (dashboard)

Voice, Stripe, and escalation email are configured in the dashboard

The API cannot create channel connections or integrations. Inbound voice is connected through the phone number you configure in the Console dashboard. There is no voice value in the SDK channel filter — voice conversations are routed through the dashboard phone number. Stripe and escalation email are also connected and configured in the dashboard. Escalation email is set under Settings → Escalation.

Open Console dashboard → Agents → select your agent.
Under Channels, enable the web chat widget and embed it in your account settings page.
Under Channels, connect an inbound voice phone number for customers who prefer to call.
Under Integrations, connect Stripe. The agent reads subscription state, processes plan changes, and retrieves payment method update links through this integration.
Under Settings → Escalation, enter the billing team email address for failed payment disputes and multi-month discrepancies.

5. Verify and go live

const integrations = await bimpe.agents.integrations.list(agent.id);
const channels = await bimpe.agents.channels.list(agent.id);
console.log("Integrations:", integrations.map((i) => i.name));
console.log("Channels:", channels.map((c) => c.type));

integrations = client.agents.integrations.list(agent.id)
channels = client.agents.channels.list(agent.id)
print("Integrations:", [i.name for i in integrations])
print("Channels:", [c.type for c in channels])

Full example

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

// 1. Find workflow
const page = await bimpe.workflows.list({ scope: "public", search: "subscription management" });
const workflow = page.data[0];

// 2. Create agent
const agent = await bimpe.agents.create(
  {
    name: "Subscription management agent",
    system_prompt:
      "You manage subscription changes. Process upgrades and downgrades via Stripe. " +
      "Run a save flow before cancellations. Explain billing line items. " +
      "Escalate failed payment disputes to the billing team.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-subscription-agent-v1" },
);

// 3. Add knowledge bases
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Plan comparison",
  content:
    "Starter £12/mo: 1 user, 5 projects. Pro £39/mo: 5 users, unlimited projects, API. " +
    "Business £99/mo: 20 users, SSO, CSM. Annual saves 17%.",
});

await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Billing guide",
  content:
    "Upgrades: prorated. Downgrades: credit next cycle. " +
    "Failed payment: retried days 3, 5, 7 — account paused after third failure.",
});

await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Retention offers",
  content:
    "Too expensive: 20% off 3 months. Not using: 1-month pause. Missing feature: 2-week extension. " +
    "One offer per attempt only.",
});

// 4. Verify integrations (Stripe must be connected in dashboard)
const integrations = await bimpe.agents.integrations.list(agent.id);
const channels = await bimpe.agents.channels.list(agent.id);
console.log("Agent ID:", agent.id);
console.log("Integrations:", integrations.map((i) => i.name));
console.log("Channels:", channels.map((c) => c.type));

// 5. Stream web chat subscription conversations
const controller = new AbortController();
const conversations = await bimpe.conversations.list(agent.id, { channel: "webchat" });
const conv = conversations.data[0];

if (conv) {
  for await (const event of bimpe.conversations.messages.stream(agent.id, conv.id, {
    signal: controller.signal,
  })) {
    console.log(event.role, event.message);
  }
}

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

# 1. Find workflow
page = client.workflows.list(scope="public", search="subscription management")
workflow = page.data[0]

# 2. Create agent
agent = client.agents.create(
    name="Subscription management agent",
    system_prompt=(
        "You manage subscription changes. Process upgrades and downgrades via Stripe. "
        "Run a save flow before cancellations. Explain billing line items. "
        "Escalate failed payment disputes to the billing team."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-subscription-agent-v1",
)

# 3. Add knowledge bases
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Plan comparison",
    "content": (
        "Starter £12/mo: 1 user, 5 projects. Pro £39/mo: 5 users, unlimited projects, API. "
        "Business £99/mo: 20 users, SSO, CSM. Annual saves 17%."
    ),
})

client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Billing guide",
    "content": (
        "Upgrades: prorated. Downgrades: credit next cycle. "
        "Failed payment: retried days 3, 5, 7 — account paused after third failure."
    ),
})

client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Retention offers",
    "content": (
        "Too expensive: 20% off 3 months. Not using: 1-month pause. Missing feature: 2-week extension. "
        "One offer per attempt only."
    ),
})

# 4. Verify integrations (Stripe must be connected in dashboard)
integrations = client.agents.integrations.list(agent.id)
channels = client.agents.channels.list(agent.id)
print("Agent ID:", agent.id)
print("Integrations:", [i.name for i in integrations])
print("Channels:", [c.type for c in channels])

# 5. Stream web chat subscription conversations
conversations = client.conversations.list(agent.id, channel="webchat")
if conversations.data:
    conv = conversations.data[0]
    for msg in client.conversations.messages.stream(agent.id, conv.id):
        print(msg.role, msg.message)

Deploy

Store your API key in BIMPEAI_API_KEY. Confirm Stripe appears in integrations.list before going live — without it, plan changes and payment method updates will fail. Update the plan comparison knowledge base via knowledgeBases.update whenever you change pricing or add a new tier; never let the agent quote stale prices. Review the retention offer knowledge base each quarter and adjust based on which offers are actually converting.

Variations

Add an Enterprise inquiry path by extending the plan comparison knowledge base with an "Enterprise: contact sales" entry and routing those conversations to your sales team email.
Use conversations.messages.list after each cancellation conversation to build a dataset of cancellation reasons for your product team.
Extend the save flow for annual subscribers by adding a pause offer that suspends rather than cancels, giving high-value customers a way back without full churn.

Subscription Management Agent

On this page