Use casesRecipes

Returns & Refund Processing Agent

Handle return requests, check eligibility against your order management system, track refund status, and schedule replacements.

DifficultyIntermediate
TrackBuilder Track or Developer Track
ChannelsWhatsAppWeb Chat
IntegrationsOrder management system (API)Stripe / payment gateway

What you'll build

An agent that guides customers through return requests, checks their order eligibility against your OMS, tracks refund status via Stripe, and schedules replacements — all without a human in the loop for standard cases.

Prerequisites

  • BimpeAI account with an API key (sk_…)
  • Read Anatomy of a workflow agent first — this recipe skips steps covered there
  • An order management system and Stripe account already connected in the Console dashboard (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: "returns refund" });
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="returns refund")
workflow = page.data[0]
print(workflow.id, workflow.name)

2. Create the agent

const agent = await bimpe.agents.create(
  {
    name: "Returns agent",
    system_prompt:
      "You process return requests. Check order eligibility using the OMS integration, initiate refunds via Stripe, and schedule replacements where applicable. Escalate to a human agent for orders over 90 days old.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-returns-agent-v1" },
);

console.log(agent.id);
agent = client.agents.create(
    name="Returns agent",
    system_prompt=(
        "You process return requests. Check order eligibility using the OMS integration, "
        "initiate refunds via Stripe, and schedule replacements where applicable. "
        "Escalate to a human agent for orders over 90 days old."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-returns-agent-v1",
)

print(agent.id)

3. Add knowledge bases

Add your returns policy so the agent can answer eligibility questions before touching the OMS.

await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Returns policy",
  content: `
    Items can be returned within 30 days of delivery in original condition.
    Perishables and personalised items are non-returnable.
    Refunds are issued to the original payment method within 5–7 business days.
    Replacement orders ship within 2 business days of return receipt.
  `,
});
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Returns policy",
    "content": (
        "Items can be returned within 30 days of delivery in original condition.\n"
        "Perishables and personalised items are non-returnable.\n"
        "Refunds are issued to the original payment method within 5-7 business days.\n"
        "Replacement orders ship within 2 business days of return receipt."
    ),
})

4. Connect channels and integrations (dashboard)

Integrations are configured in the dashboard

The OMS and Stripe connections are read-only through the API. You configure them in the Console and the SDK can list what is active, but cannot create or modify these connections.

  1. Open Console dashboard → Agents → select your agent.
  2. Go to Channels → connect your WhatsApp Business number.
  3. Go to Channels → add the web chat widget.
  4. Go to Integrations → connect your order management system.
  5. Go to Integrations → connect Stripe using your API keys.

5. Go live

Verify that your integrations are visible before opening to customers:

const integrations = await bimpe.agents.integrations.list(agent.id);
console.log("Integrations:", integrations.map((i) => i.type));
integrations = client.agents.integrations.list(agent.id)
print("Integrations:", [i.type for i in integrations])

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: "returns refund" });
const workflow = page.data[0];

// 2. Create agent
const agent = await bimpe.agents.create(
  {
    name: "Returns agent",
    system_prompt:
      "You process return requests. Check order eligibility using the OMS integration, initiate refunds via Stripe, and schedule replacements where applicable.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-returns-agent-v1" },
);

// 3. Add returns policy
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Returns policy",
  content:
    "Items can be returned within 30 days of delivery. Refunds process in 5-7 business days.",
});

// 4. Verify integrations (OMS + Stripe must be connected in the dashboard first)
const integrations = await bimpe.agents.integrations.list(agent.id);
console.log("Integrations:", integrations.map((i) => i.type));

// 5. Stream web chat 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="returns refund")
workflow = page.data[0]

# 2. Create agent
agent = client.agents.create(
    name="Returns agent",
    system_prompt=(
        "You process return requests. Check order eligibility using the OMS integration, "
        "initiate refunds via Stripe, and schedule replacements where applicable."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-returns-agent-v1",
)

# 3. Add returns policy
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Returns policy",
    "content": "Items can be returned within 30 days of delivery. Refunds process in 5-7 business days.",
})

# 4. Verify integrations (OMS + Stripe must be connected in the dashboard first)
integrations = client.agents.integrations.list(agent.id)
print("Integrations:", [i.type for i in integrations])

# 5. Stream web chat 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. Run the setup script once and verify that both integrations appear in the list before routing live traffic. Use the escalation_email field on agents.update to receive alerts when the agent escalates a case outside the 30-day window.

Variations

  • Add a second knowledge base entry for exchange policy to keep returns and exchanges in the same agent.
  • Update the returns policy knowledge base via knowledgeBases.update whenever your policy changes without recreating the agent.
  • Add a rules field to the agent to hard-block refund confirmation on non-returnable SKU categories.

Restaurant Ordering & Table Booking

Let diners browse your menu, filter by dietary needs, book a table, or place a takeout order — with upsell prompts baked into the flow.

SaaS Helpdesk Agent

Answer tier-1 support questions from your help docs, create and track tickets in your ticketing system, and route complex cases to a human agent.

On this page

What you'll buildPrerequisitesSteps1. Find the workflow2. Create the agent3. Add knowledge bases4. Connect channels and integrations (dashboard)5. Go liveFull exampleDeployVariations