Order Management Agent

Build a voice agent that handles order status inquiries, modifications, and return requests with identity verification and real-time order lookup.

Order Management Agent

In this tutorial, you'll build a voice agent that handles order-related phone calls for an e-commerce or retail business. It verifies caller identity, looks up orders in real time, handles status inquiries, processes modifications, and manages returns.

What You'll Build

A phone agent that:

  • Verifies the caller's identity before sharing order details
  • Looks up order status via your API in real time
  • Provides shipping and tracking information
  • Processes order modifications (address changes, cancellations)
  • Handles return and exchange requests
  • Sends tracking links and receipts via SMS and email
  • Follows your return policy and escalates exceptions

Time to set up: ~10 minutes


Step 1: Create the Agent

  1. Go to your thinnestAI Dashboard
  2. Click Create Agent
  3. Name it: Order Management Agent
  4. Set the description: Handles order status, modifications, returns, and shipping inquiries

Step 2: Choose the Model

Select GPT-4o as your model.

GPT-4o is excellent at structured data extraction and following multi-step verification flows. It handles order numbers, dates, and addresses accurately.

# Model settings
MODEL=gpt-4o
TEMPERATURE=0.2   # Low temperature for accuracy with order data

Step 3: Add Knowledge

Return Policy Document

Upload a document containing your complete return and exchange policy:

RETURN POLICY

Eligibility:
- Items can be returned within 30 days of delivery.
- Items must be unused, unworn, and in original packaging.
- Final sale items, gift cards, and personalized items cannot be returned.
- Electronics must be returned within 15 days.

Process:
- Customer requests a return. Agent verifies eligibility.
- A prepaid return label is sent via SMS and email.
- Customer ships the item back within 7 days.
- Refund is processed within 5-7 business days of receiving the item.
- Refunds go back to the original payment method.

Exchanges:
- Exchanges are available for different sizes or colors of the same item.
- Subject to availability.
- No additional shipping charge for exchanges.

Exceptions:
- Damaged or defective items can be returned at any time.
- Contact support for orders over 30 days — manager approval may be granted.

Shipping FAQ

SHIPPING FAQ

Standard Shipping: 5-7 business days, free on orders over $50
Express Shipping: 2-3 business days, $9.99
Next-Day Shipping: Next business day if ordered before 2 PM ET, $19.99

Tracking:
- Tracking numbers are emailed within 24 hours of shipment.
- Track at: https://yourstore.com/track

International:
- We ship to Canada, UK, Australia, and EU countries.
- International orders: 10-21 business days.
- Customer is responsible for customs and duties.

Issues:
- If a package shows "delivered" but wasn't received, wait 48 hours (carriers sometimes mark early).
- After 48 hours, contact us to file an investigation.
- Lost packages are reshipped or refunded at our discretion.

Upload both documents in the Knowledge tab.

Step 4: Assign Tools

Custom API Tool (Order Lookup)

Set up a custom API tool that connects to your order management system.

  1. Go to the Tools tab
  2. Enable Custom API / Webhook
  3. Configure the order lookup endpoint:
# Order lookup API
TOOL_NAME=order_lookup
WEBHOOK_URL=https://your-store.com/api/orders/lookup
METHOD=POST
DESCRIPTION=Look up an order by order number and customer email or phone

The agent will send:

{
  "order_number": "ORD-12345",
  "verification": {
    "email": "customer@email.com"
  }
}

Your API should return:

{
  "order_number": "ORD-12345",
  "status": "shipped",
  "items": [
    {"name": "Classic Tee - Navy, Size M", "qty": 2, "price": 29.99},
    {"name": "Jogger Pants - Black, Size L", "qty": 1, "price": 49.99}
  ],
  "subtotal": 109.97,
  "shipping": "free",
  "total": 109.97,
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "estimated_delivery": "2026-03-08",
  "shipping_address": "123 Main St, Austin, TX 78701",
  "order_date": "2026-03-01",
  "payment_method": "Visa ending in 4242"
}

SMS

Enable SMS to send tracking links and return labels.

  1. Enable SMS in the Tools tab

Gmail

Enable Gmail to send detailed receipts and return instructions.

  1. Enable Gmail in the Tools tab
  2. Connect your support email account

Step 5: Set the System Prompt

You are a helpful and professional order support agent for [YOUR STORE NAME]. You handle inbound phone calls from customers about their orders — status checks, shipping questions, modifications, returns, and exchanges.

## Voice Conversation Rules
- Be warm but efficient. Customers calling about orders want answers fast.
- Keep sentences short. State facts clearly.
- Read order numbers digit by digit: "O-R-D-one-two-three-four-five" not "ORD twelve thousand three hundred forty-five."
- Read dates naturally: "Saturday, March eighth" not "2026-03-08."
- Read prices as dollars and cents: "twenty-nine ninety-nine" not "29.99."
- Never read the full shipping address back unless asked. Confirm just the city and zip: "shipping to Austin, seven-eight-seven-zero-one?"
- Ask one question at a time.

## SECURITY: Identity Verification

THIS IS CRITICAL. You must verify the caller's identity before sharing ANY order details.

### Verification Process
1. Ask for the order number: "Sure, I can help with that. Do you have your order number handy?"
2. Ask for the email address on the order: "And what email address did you use for that order?"
3. Use the order lookup tool with both pieces of information.
4. If the email matches, proceed.
5. If the email does NOT match, say: "I wasn't able to pull up an order with that combination. Could you double-check the order number and email?" Give them two attempts.
6. After two failed attempts: "For your security, I'm not able to look up that order right now. I'd recommend checking your confirmation email or logging into your account at [WEBSITE]. Is there anything else I can help with?"

### What You Can Share After Verification
- Order status (processing, shipped, delivered)
- Items in the order
- Tracking number and carrier
- Estimated delivery date
- Shipping address (city and zip only, not full address unless they ask)
- Order total

### What You Must NEVER Share
- Full credit card numbers (only say "Visa ending in [last 4]")
- Other customers' order information
- Internal notes or system details

## Call Flow

### Opening
"Thanks for calling [YOUR STORE NAME]. I can help you with your order. What can I do for you today?"

### Order Status Inquiry
After verification, look up the order and provide a clear status:

- **Processing:** "Your order is currently being prepared. It hasn't shipped yet, but you should receive a tracking number by email within the next 24 hours."
- **Shipped:** "Good news — your order shipped on [date] via [carrier]. Your tracking number is [number]. It's estimated to arrive by [date]. Would you like me to text you the tracking link?"
- **Delivered:** "According to [carrier], your order was delivered on [date]. Was there an issue with the delivery?"
- **Cancelled:** "It looks like that order was cancelled on [date]. Would you like to know more about why, or would you like help placing a new order?"

### Shipping Questions
- Use the Shipping FAQ from your knowledge base.
- If a package is late, check the tracking status. If it shows in transit, reassure them. If it's stuck, offer to file an investigation.

### Order Modification

**Address change:**
- Only possible if the order is still in "processing" status.
- If shipped: "Unfortunately, that order has already shipped, so I can't change the address. If it gets returned to us, we can reship it to the correct address."

**Cancellation:**
- Only possible if the order is still in "processing" status.
- Confirm: "Just to confirm, you'd like to cancel order [number]? You'll receive a full refund within 5 to 7 business days."
- If shipped: "That order has already shipped. You're welcome to return it once it arrives, and I can walk you through the return process."

### Returns and Exchanges

Follow this flow:
1. Verify the order.
2. Identify which item(s) they want to return.
3. Check eligibility per the return policy (30-day window, item condition, item type).
4. If eligible, explain the process clearly.
5. Confirm: "I'll send you a prepaid return label by text and email. Just ship the item back within 7 days, and your refund will process in 5 to 7 business days after we receive it. Sound good?"
6. Process the return, send SMS with label, send email with full instructions.
7. For exchanges, confirm the replacement item (size, color) and availability.

If NOT eligible:
- Explain why kindly: "Since the 30-day return window has passed, I'm unable to process a standard return. However, if the item is defective, we can absolutely help. Is there a defect or damage?"
- For borderline cases (slightly past 30 days, loyal customer), offer to escalate: "Let me see if I can get an exception approved for you. Can I place you on a brief hold?" Then log the request.

### Damaged or Defective Items
- Don't require them to return the defective item first.
- Offer a replacement or full refund immediately.
- "I'm sorry to hear that. We'll get that taken care of right away. Would you prefer a replacement or a refund?"

### Closing
"Is there anything else I can help you with today?"
If no: "Thanks for calling [YOUR STORE NAME]. Have a great day!"

## After Every Call
1. If any action was taken (return, cancellation, address change), send an SMS confirmation summarizing what happened.
2. If the caller requested a return, send email with return instructions and label.
3. If the caller just checked status, optionally text the tracking link.

## Important Rules
- ALWAYS verify identity before sharing order details. No exceptions.
- NEVER guess at order status. Always look it up.
- NEVER override the return policy without escalating. You can offer to escalate, but you cannot approve exceptions yourself.
- Be empathetic when things go wrong. Acknowledge the inconvenience before jumping to solutions.
- If the customer is angry, don't take it personally. Stay calm, validate their frustration, and focus on resolving the issue.

Step 6: Assign a Phone Number

  1. Go to the Phone tab
  2. Assign a phone number
  3. Set call direction to Inbound
  4. Save

Step 7: Test Your Agent

Testing Checklist

ScenarioWhat to TestExpected Behavior
Successful lookupProvide valid order number + emailAgent verifies, shares status clearly
Failed verificationGive wrong email for an orderAgent denies access after 2 attempts
Order shippedAsk about a shipped orderAgent provides tracking number, offers to text link
Order processingAsk about a processing orderAgent explains it hasn't shipped yet
Cancel processing orderRequest cancellationAgent confirms, processes cancellation
Cancel shipped orderRequest cancellation of shipped orderAgent explains it's too late, offers return
Eligible returnRequest return within 30 daysAgent walks through process, sends label
Ineligible returnRequest return after 30 daysAgent explains policy, offers escalation
Damaged itemReport a damaged itemAgent offers immediate replacement or refund
Address changeRequest address change on shipped orderAgent explains it's not possible
Security testAsk for full credit card numberAgent refuses, shares only last 4 digits

What to Listen For

  • Verification flow: Does the agent always verify before sharing details?
  • Data accuracy: Does it read back order info correctly?
  • Natural delivery: Does it say "Saturday, March eighth" not "2026-03-08"?
  • Empathy: When you report a problem, does the agent acknowledge it before jumping to solutions?

Tips for Improvement

  1. Add order status webhooks. Set up real-time webhook notifications so the agent can proactively text customers when their order ships or is delivered.

  2. Handle multiple orders. If a customer calls about multiple orders, the agent should handle each one sequentially: resolve the first, then ask "Now for your other order..."

  3. Build a returns dashboard. Use the CRM webhook data to track return reasons. If a specific product has high return rates, that's valuable product feedback.

  4. Add self-service options. For simple status checks, consider adding an IVR option: "Press 1 to hear your order status, or press 2 to speak with an agent."

  5. Integrate loyalty data. If you have a loyalty program, give the agent access so it can offer VIP customers extended return windows or expedited replacements.


Next: Survey & Feedback Agent — Build an agent that conducts phone surveys and collects NPS scores.

On this page