Blog · November 18, 2026
Self-service returns in Zendesk Messenger with Stackable: build it with Claude Code (part 2)
Build self-service returns into Zendesk Messenger with Claude Code: pick items, confirm with a button, post a receipt in chat and hand off to an agent.
By Rob Bowers, CTO - Stackable Labs
In part 1, Build your first Stackable extension with Claude Code, we installed the Claude Code plugin, scaffolded a project and shipped an order-status card that sits next to the Zendesk messenger. It reads an order and can share the status into the chat. Useful, but read-only.
This time the card acts. By the end of this post, a customer can pick the items they want to send back, confirm the return with a real button, get a receipt in the conversation, and reach a person who already knows which order it's about.
Those four steps aren't arbitrary. They're the four jobs from Beyond the FAQ bot: show the state, confirm with a real control, leave a receipt, hand off with context. In When the customer's AI comes knocking, we argued that a screen like this is also where a person approves what their own AI asked for. And in Interactive UI for AI agents, we covered why the widget, not the wall of text, is where agents that act do their acting. This post is the code.
What you'll need
- The
order-statusproject from part 1, with thestackable-extension-devplugin installed in Claude Code - An orders API that also returns each order's line items, plus a
POST /returnsendpoint. We'll keep usingapi.example.comas a stand-in for yours.
1. Ask Claude for the flow
Here's the prompt:
Turn the order card in slot.content into a return flow:
1. List the order's items with a checkbox for each returnable item,
and a "Start a return" button.
2. Add a confirm step that shows exactly what's being returned, with
"Confirm return" and "Back" buttons. No typed confirmation.
3. On confirm, POST { orderId, itemIds } to https://api.example.com/returns
with the same secret API key. Then post a receipt into the conversation
with messaging.send: a link to the return label, and the order and
return IDs as metadata.
4. Add a "Talk to someone" button that starts a new conversation tagged
with the order, using a Zendesk ticket field ID that installers enter
as a regular (non-secret) setting.
Keep the current step in a shared store. Update the manifest, then validate it.
The plugin's Agent Skills cover the parts that are easy to get wrong here: which permission actions.invoke needs, which messaging.send payload fields exist, what useSettings() can and can't see, and how secret placeholders work. As in part 1, your output will vary a little from run to run. Here's what we ended up with.
2. The manifest
{
"name": "Order Status",
"version": "1.1.0",
"targets": ["slot.content"],
"permissions": ["context:read", "data:fetch", "messaging:send", "actions:invoke"],
"allowedDomains": ["api.example.com"],
"settingsSchema": [
{
"identifier": "apiKey",
"label": "API Key",
"type": "text",
"secret": true,
"required": true,
"description": "Stored encrypted. Injected server-side into outbound requests."
},
{
"identifier": "orderFieldId",
"label": "Order number ticket field ID",
"type": "text",
"required": false,
"description": "Optional. The Zendesk custom field that should hold the order number when a customer asks for a person."
}
]
}
Two changes from part 1. Here's what each capability in the flow needs:
| Capability | Used for | Permission |
|---|---|---|
context.read (useContextData, useSettings) | Customer email, the regular orderFieldId setting | context:read |
data.fetch | Read the order, create the return | data:fetch |
messaging.send (useMessaging) | The receipt in the thread | messaging:send |
actions.invoke | The handoff | actions:invoke |
actions:invoke is the only new permission. orderFieldId is new too, and it's deliberately not secret. A field ID isn't sensitive, and the code needs to read it. That's exactly the split the Instance Settings guide describes: secrets go out through placeholders, and regular values come back through useSettings().
allowedDomains doesn't change, because the new POST goes to the same host.
3. A store for the steps
Claude put the order types and the flow's current step in the template's store.ts:
import { createStore } from '@stackable-labs/sdk-extension-react'
export type OrderItem = { id: string; name: string; quantity: number; returnable: boolean }
export type Order = { id: string; status: string; eta: string; items: OrderItem[] }
export type ViewState =
| { type: 'order' }
| { type: 'confirm' }
| { type: 'done'; returnId: string; labelUrl?: string }
export interface AppState {
viewState: ViewState
selectedIds: string[]
}
export const appStore = createStore<AppState>({
viewState: { type: 'order' },
selectedIds: [],
})
There are no URLs inside an extension, so the store is the router. A discriminated union keeps the views honest: a done view can't exist without a returnId. (More in Store & Navigation.)
4. Where the secrets live
Both API calls go through one wrapper in src/lib/api.ts:
import type { FetchRequestInit, FetchResponse } from '@stackable-labs/sdk-extension-contracts'
import type { Order } from '../store'
type FetchFn = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>
export type ReturnResult = { id: string; labelUrl?: string }
const API_BASE_URL = 'https://api.example.com'
const headers = { 'X-Api-Key': '{{settings.apiKey}}' }
export const createOrdersApi = (fetchData: FetchFn) => ({
async getLatestOrder(email: string): Promise<Order | null> {
const result = await fetchData(`${API_BASE_URL}/orders/latest?email=${encodeURIComponent(email)}`, { headers })
return result.ok ? (result.data as Order) : null
},
async createReturn(orderId: string, itemIds: string[]): Promise<ReturnResult> {
const result = await fetchData(`${API_BASE_URL}/returns`, {
method: 'POST',
headers,
body: { orderId, itemIds },
})
if (!result.ok) {
throw new Error(`createReturn failed: ${result.status}`)
}
return result.data as ReturnResult
},
})
export type OrdersApi = ReturnType<typeof createOrdersApi>
Nothing new for reads, and that's the point. Writes follow the same rules:
- The proxy makes the call.
data.fetchrequests are proxied through the Stackable platform, and only to hosts inallowedDomains. Requests anywhere else are rejected. - The key stays on the server.
{{settings.apiKey}}is a placeholder. The proxy substitutes the real value for that one request. Secret values are encrypted with a per-Instance key and never sent to the browser. - Placeholders only work in header values. Not in URLs, and not in the body. So don't try to template a secret into
{ orderId, itemIds }.
Your returns endpoint is still your API, so it should still check that the order belongs to the customer and that each item can be returned. The checkbox in the next step is UX, not authorization.
5. Show the exact thing
Content.tsx loads the order the same way part 1 did, then hands it to whichever view the store says is current:
import { useEffect, useMemo, useState } from 'react'
import { Surface, ui, useCapabilities, useContextData, useStore } from '@stackable-labs/sdk-extension-react'
import { createOrdersApi } from '../lib/api'
import { appStore, type Order } from '../store'
import { ConfirmView } from '../views/ConfirmView'
import { DoneView } from '../views/DoneView'
import { OrderView } from '../views/OrderView'
export const Content = () => {
const { fetch: fetchData } = useCapabilities().data
const { loading, customerEmail } = useContextData()
const viewState = useStore(appStore, (s) => s.viewState)
const [order, setOrder] = useState<Order | null>()
const api = useMemo(() => createOrdersApi(fetchData), [fetchData])
useEffect(() => {
if (loading) {
return
}
if (customerEmail == undefined || customerEmail === '') {
setOrder(null)
return
}
api.getLatestOrder(customerEmail)
.then(setOrder)
.catch(() => setOrder(null))
}, [api, loading, customerEmail])
if (loading || order === undefined) {
return (
<Surface id="slot.content">
<ui.Skeleton height="96px" />
</Surface>
)
}
if (order === null) {
return (
<Surface id="slot.content">
<ui.Text tone="muted">No recent orders found.</ui.Text>
</Surface>
)
}
return (
<Surface id="slot.content">
{(viewState.type === 'order') && <OrderView order={order} />}
{(viewState.type === 'confirm') && <ConfirmView order={order} api={api} />}
{(viewState.type === 'done') && (
<DoneView order={order} returnId={viewState.returnId} labelUrl={viewState.labelUrl} />
)}
</Surface>
)
}
The first view is part 1's card, plus a checkbox for each item:
import { ui, useStore } from '@stackable-labs/sdk-extension-react'
import { appStore, type Order } from '../store'
export const OrderView = ({ order }: { order: Order }) => {
const selectedIds = useStore(appStore, (s) => s.selectedIds)
const toggle = (id: string, checked: boolean) => {
const others = selectedIds.filter((selectedId) => selectedId !== id)
appStore.set({ selectedIds: checked ? [...others, id] : others })
}
return (
<ui.Card>
<ui.CardHeader>
<ui.Heading level="3">Order {order.id}</ui.Heading>
</ui.CardHeader>
<ui.CardContent>
<ui.Stack direction="column" gap="3">
<ui.Inline gap="2">
<ui.Badge hue="blue">{order.status}</ui.Badge>
<ui.Text tone="muted">Expected {order.eta}</ui.Text>
</ui.Inline>
{order.items.map((item) => (
<ui.Inline key={item.id} gap="2">
<ui.Checkbox
id={`item-${item.id}`}
checked={selectedIds.includes(item.id)}
disabled={!item.returnable}
onChange={(e) => toggle(item.id, e.target.value === 'true')}
/>
<ui.Label htmlFor={`item-${item.id}`}>{item.name} × {item.quantity}</ui.Label>
</ui.Inline>
))}
<ui.Button
disabled={selectedIds.length === 0}
onClick={() => appStore.set({ viewState: { type: 'confirm' } })}
>
Start a return
</ui.Button>
</ui.Stack>
</ui.CardContent>
</ui.Card>
)
}
One detail Claude got right that you'd likely trip on: ui.Checkbox's onChange hands you e.target.value as the string 'true' or 'false', not a boolean. UI events cross from the host back into your extension as serialized values, so compare against the string.
6. Confirm with a real control
The confirm step repeats the exact order and items, then waits for a tap:
import { useState } from 'react'
import { ui, useMessaging, useStore } from '@stackable-labs/sdk-extension-react'
import type { OrdersApi, ReturnResult } from '../lib/api'
import { appStore, type Order } from '../store'
import { HandoffButton } from './HandoffButton'
export const ConfirmView = ({ order, api }: { order: Order; api: OrdersApi }) => {
const selectedIds = useStore(appStore, (s) => s.selectedIds)
const [send] = useMessaging()
const [submitting, setSubmitting] = useState(false)
const [failed, setFailed] = useState(false)
const items = order.items.filter((item) => selectedIds.includes(item.id))
const sendReceipt = async (created: ReturnResult) => {
const summary = items.map((item) => `${item.name} × ${item.quantity}`).join(', ')
try {
await send({
kind: 'text',
body: `Return ${created.id} started for order ${order.id}: ${summary}.`,
actions: (created.labelUrl == undefined)
? undefined
: [{ type: 'link', label: 'Download return label', url: created.labelUrl }],
metadata: { orderId: order.id, returnId: created.id },
})
} catch {
// invalid_message, rate_limited or upstream_error: the return still exists
}
}
const confirm = async () => {
setSubmitting(true)
setFailed(false)
let created: ReturnResult
try {
created = await api.createReturn(order.id, selectedIds)
} catch {
setFailed(true)
setSubmitting(false)
return
}
await sendReceipt(created)
appStore.set({ viewState: { type: 'done', returnId: created.id, labelUrl: created.labelUrl } })
}
return (
<ui.Card>
<ui.CardHeader>
<ui.Heading level="3">Return these items?</ui.Heading>
</ui.CardHeader>
<ui.CardContent>
<ui.Stack direction="column" gap="2">
<ui.Text tone="muted">Order {order.id}</ui.Text>
{items.map((item) => (
<ui.Text key={item.id}>{item.name} × {item.quantity}</ui.Text>
))}
{failed && (
<ui.Alert variant="destructive" title="We couldn't start the return">
Nothing was changed. Try again, or talk to someone.
</ui.Alert>
)}
<ui.Inline gap="2">
<ui.Button disabled={submitting} onClick={confirm}>Confirm return</ui.Button>
<ui.Button
variant="outline"
disabled={submitting}
onClick={() => appStore.set({ viewState: { type: 'order' } })}
>
Back
</ui.Button>
</ui.Inline>
{failed && <HandoffButton orderId={order.id} />}
</ui.Stack>
</ui.CardContent>
</ui.Card>
)
}
The confirmation is a button press on a screen that names the order and every item. Nobody has to type YES. Confirm return disables itself while the request is in flight, so a double tap can't start two returns. If the API fails, the card says plainly that nothing changed and offers a person.
7. Leave a receipt in the thread
sendReceipt above is the receipt. A few things about messaging.send worth knowing:
- The order of operations matters. The receipt goes out after the return exists, so the transcript never says something happened that didn't.
useMessaging()handles the "no conversation" case. If there's no active conversation,send()resolves tonullwithout posting, so the return still completes and the done view still shows it. Its three actionable errors (invalid_message,rate_limited,upstream_error) throw. We catch them because the return succeeded either way.- A
linkaction puts the label one tap away, right in the thread. metadatadoesn't render in the messenger, but it travels with the message. The host adds its ownstackable.*block (extension, Instance and call IDs) that extensions can't override.- You don't set the author. As in part 1, the label comes from the brand admin's setting for their install, falling back to your extension's name.
One trade-off: the receipt is posted from the customer's browser, after the return is created. If they close the page between those two steps, the return exists but the receipt never posts. Your returns API is the source of truth, so if you need a record in Zendesk every time, write it from your backend too.
8. Hand off with context
Last job: when the customer wants a person, the person should already know what's going on. Here's HandoffButton:
import { ui, useCapabilities, useSettings } from '@stackable-labs/sdk-extension-react'
export const HandoffButton = ({ orderId, returnId }: { orderId: string; returnId?: string }) => {
const { invoke } = useCapabilities().actions
const settings = useSettings()
const orderFieldId = settings.orderFieldId as string | undefined
const talkToSomeone = async () => {
try {
await invoke('newConversation', {
tags: ['stackable', (returnId == undefined) ? 'return-needs-help' : 'return-started'],
fields: (orderFieldId == undefined || orderFieldId === '') ? [] : [{ id: orderFieldId, value: orderId }],
metadata: (returnId == undefined) ? { orderId } : { orderId, returnId },
})
} catch {
// the host didn't accept the action
}
}
return <ui.Button variant="outline" onClick={talkToSomeone}>Talk to someone</ui.Button>
}
actions.invoke('newConversation', ...) starts a new messaging conversation with tags, custom fields and metadata already set. It doesn't skip the line: the new conversation goes through your messaging setup like any other, so if an AI agent or bot answers first in your messenger, it answers this one too. When the ticket is created, Zendesk adds the tags and, if the installer set orderFieldId, the order number field, so your triggers and routing can use them and the agent who picks it up sees them on the ticket. If the customer's current conversation hasn't become a ticket yet, setConversationTags and setConversationFields take the same tags and fields on their own. Some Zendesk details to know, from the docs:
- Tags are capped at 20, and Zendesk lowercases and sanitizes them.
- Each call replaces the tags or fields. It doesn't add to them.
- Tags and fields are added to a ticket when it's created. They can't change a ticket that already exists.
- A conversation field only works for a custom ticket field that an admin has set up to let end users set its value. Fields also depend on a Zendesk-side feature flag (
web_widget_conversation_ticket_metadata). metadatastays on the conversation. Zendesk doesn't turn it into ticket fields, so anything the agent needs to see belongs in a tag or a field.
DoneView ties it together: a confirmation, the label link, and the same button with the return ID attached:
import { ui } from '@stackable-labs/sdk-extension-react'
import type { Order } from '../store'
import { HandoffButton } from './HandoffButton'
export const DoneView = ({ order, returnId, labelUrl }: { order: Order; returnId: string; labelUrl?: string }) => (
<ui.Card>
<ui.CardContent>
<ui.Stack direction="column" gap="2">
<ui.Heading level="3">Return started</ui.Heading>
<ui.Text>Return {returnId} for order {order.id}.</ui.Text>
{(labelUrl != undefined) && (
<ui.Link href={labelUrl} target="_blank" rel="noopener noreferrer">Download return label</ui.Link>
)}
<HandoffButton orderId={order.id} returnId={returnId} />
</ui.Stack>
</ui.CardContent>
</ui.Card>
)
On the other side of that handoff, a Zendesk agent with agnoStack sees the order and customer right in their workspace. And the same extension model is heading there: agnoStack 6.1.0 gave an early look at Stackable App Extensions, with extension slots inside the agent experience.
9. Test it
pnpm dev runs the local preview with mock customer data. As in part 1, the preview calls data.fetch straight from the browser, so secret placeholders aren't filled in. Point it at a test endpoint that doesn't need the key. The handoff is logged to the browser console, so you can check its payload. The receipt is skipped, because the preview has no live conversation.
To see the whole thing for real, use pnpm preview and the _stackable_dev parameter on a site where the extension is installed, just like in part 1. Then you can watch the receipt land in the thread and the new conversation open with its tags.
10. Ship it
Ask Claude to run validate_manifest and validate_permissions. Then rebuild, redeploy to the same Bundle URL (see Deploy), and run the CLI's update command. It walks you through syncing the new actions:invoke permission and the orderFieldId setting to the registry, so installers see the new field.
If the extension is already published, there's nothing to resubmit: installs pick up the new bundle from the same URL, and update has synced the manifest. If you haven't listed it yet, the automated bundle scan runs when you submit it for review, comparing the permissions, targets and allowedDomains your manifest declares with what it finds in your bundle. Either way, actions.invoke won't work without actions:invoke in the manifest, and data.fetch only goes to api.example.com.
Where to go next
You now have an extension that does all four jobs: it shows the exact order, confirms with a real button, leaves a receipt, and hands off with context. For how this runtime fits together under the hood, the agnoStack blog has a good walkthrough of how Stackable Extensions work, and Stackable Messenger shows the brand-side experience these extensions plug into.
The developer docs cover every capability used here. When you're ready, create your account and build the flow your customers keep asking for in chat.