On this page
Build an order-support and refund flow
A customer contacts support about an order. They may need an invoice explained, a replacement reviewed or a damaged-order refund. The agent must first verify access, then follow the rules for the requested remedy.
Build this flow in Studio, connect account and refund services, and check the final business result. The example records are fictional. Your team sets the verification and refund rules and implements the endpoints.
Map the customer’s choices
Start with the account-verification component. After access is confirmed, ask what the customer needs and route to invoice help, a replacement case, refund review or a specialist. Put refund eligibility and confirmation in a separate component.
| Path | Business rule | Expected outcome |
|---|---|---|
| Access verified | The business verification endpoint authorizes access | Continue to account lookup |
| Access not verified | Never disclose protected account facts | End with a safe next step |
| Invoice question | Explain returned account facts with approved policy | Confirm the question was answered or escalate |
| Replacement request | Record the item and requested remedy | Create a review/replacement case; do not claim shipment |
| Refund eligible | Eligibility comes from the business policy endpoint | Ask for explicit confirmation before requesting the write |
| Refund ineligible or uncertain | Avoid unsupported promises and repeated writes | Create a manual-review case |
| Specialist unavailable | A failed connection is not a completed handoff | Record an agreed callback or alternate route |
Verify access before reading account facts
For the business access check below, your endpoint decides whether the caller may see the record. If you need verification through a private telephone keypad, use the private verification workflow instead of collecting sensitive answers in the conversation.
The verification component collects the information your business procedure requires, then calls verify_account_access. Its response provides the authorization decision. A branch in the parent flow checks that result before calling lookup_account.
Use a response variable mapping such as identity_verified → $.authorized for the business endpoint's boolean decision. Continue only when the endpoint returns authorized access. Missing or invalid data goes to the failure path. Your endpoint performs the access check.
Test verified access, a wrong answer, refusal, an unknown account and a verification-service outage separately. For an unverified caller, offer a public support route without disclosing account details.
Classify and route the request
Use extraction for conversational facts such as request type and order reference. Set an enum for the supported request types instead of leaving every downstream branch to match free-form wording.
Route on the extracted value, with an explicit fallback for unsupported or unclear requests. A “refund” intent selects refund review. Eligibility still comes from the business endpoint, and the write still needs the customer’s confirmation.
Pin the knowledge this version can use
Upload your return policy and replacement handbook, wait for readiness and select the documents on the draft. Publishing fixes the selected document versions for that publication. The third source is still indexing, so it is not selected.
Use knowledge for explanations and policy context. Use the business eligibility endpoint for the authoritative decision on a specific order. Route missing or contradictory policy evidence to a specialist.
See Knowledge for upload, indexing and document versions. Select the documents on the draft before publishing; uploading alone does not add them to an agent.
Bind the business actions
The example uses five actions: verify account access, read the account, check eligibility, request a refund and create a ticket. Each is an HTTPS service you own.
Define the action's request and response schema, credential reference, timeout and idempotency behavior. For create_refund, the business endpoint must ensure that repeating the same effect key does not create a second refund. Cumulus records the attempt; the downstream transaction contract makes repeating the request safe.
Example business responses might include { "authorized": true }, { "eligible": true } and { "state": "confirmed", "refund_id": "REF-DEMO-81" }. Define these fields in your service responses and map them into flow variables. Require the fields used by the next branch.
Review eligibility and get confirmation
Keep the eligibility decision, caller confirmation and write separate. The caller should hear the approved remedy before being asked to authorize it. Route an ineligible result to review.
Wait for the result when the next statement depends on it. A status message such as “I am checking that now” describes work in progress; it does not claim that the refund succeeded.
If the response confirms completion, state the returned identifier and agreed next step. If the outcome is uncertain, reconcile it with the business service before another write. The uncertain-action example shows the record an operator reviews.
Handle an unavailable specialist
Create the review case before a handoff when your process requires it. Configure the transfer destination and failure path. If the specialist cannot be reached, explain that clearly and record the alternate next step.
Test busy destinations, failed transfers, an uncertain transfer result and caller refusal. Use a carrier call to a number you own to check routing and media behavior.
Notify your application and inspect the result
Use signed lifecycle webhooks to tell your application that a run ended or an output became available. Verify signatures and deduplicate deliveries by event identity. Before closing a case, read the run, action receipts and downstream transaction.
For an API-started phone run, use your published agent and authorized target. This request demonstrates per-run context:
<!-- operation:runs.create -->{
"channel": "phone",
"agent_id": "order-resolution",
"to": "+14155550123",
"from": "+14155550100",
"dynamic_variables": { "business_name": "Acme", "account_reference": "DEMO-42" },
"metadata": { "account_reference": "DEMO-42", "order_id": "ORDER-DEMO-81" }
}
Send it to Start a run with your environment's API key and a retained Idempotency-Key. Wait for the run to complete, then inspect the refund action response and receipt before closing the customer’s case.
Acceptance cases before release
| Case | Checkable expectation |
|---|---|
| Caller refuses verification | No protected account disclosure or lookup that bypasses authorization |
| Eligibility endpoint returns false | No refund request |
| Caller declines the remedy | No refund write |
| Refund endpoint times out after a possible commit | Reconciliation/manual review; no blind second write |
| Policy document is unavailable | Defined fallback; no invented policy |
| Specialist is busy | The configured fallback is visible in the run |
Use regression testing for repeatable conversational checks and mocks. Complete real business-endpoint and carrier acceptance separately. Then release the tested publication.
After release, use the run ID to find the executed publication, selected path and refund receipt. Keep the downstream refund or review-case ID with the same business record.










