Returns and warranty claim desk that follows your policy

Build me an internal app my support team opens to work returns, damage and warranty claims. Today every claim is decided from memory plus a spreadsheet, so two agents give two different answers to the same situation. I want one queue, one written policy, one recommendation and one ledger. The app has two tabs: a claim queue where reps work claims, and a ledger view that reads the claim history back.

The app stores its own settings that an admin edits inside the app: the full text of our returns and warranty policy, the return window in days (default 30), the list of Kustomer conversation tags that count as claims (returns, damages, warranty), the repeat claimant threshold (default 3), the Google Sheets spreadsheet id and tab name for the claims ledger, and the store credit amounts reps are allowed to issue. The policy text is what the assessment agent scores against, so it has to be editable without rebuilding the app.

The claim queue is built from Kustomer. Use Search Customers to pull customers with recent activity, then Get Conversations by Customer for each one, and keep only conversations carrying one of the configured claim tags. For each of those conversations, match the customer into Shopify: Search Customers with their email address, then Get Customer Orders, and pick the order the thread is about (the order number mentioned in the thread if there is one, otherwise the most recent order before the claim). Pull the full order with Get Order and the delivery date with List Fulfillments for Order. Each queue row shows the conversation subject and last message preview, the customer, the matched Shopify order with its number, date and value, the delivery date, the number of days elapsed since delivery, and a clear badge for whether that lands inside or outside the configured policy window. Sort oldest claim first, and give me filters for inside versus outside window, claim status, and assigned agent (agents come from Get Users).

Clicking a row opens the claim detail. It shows the full conversation thread from Get Messages by Conversation in reading order, the internal notes already on it from Get Notes by Conversation, the conversation record from Get Conversation by ID, the order line items and fulfillment tracking from Shopify, and the customer's prior claim history: their other tagged conversations from Get Conversations by Customer plus any prior rows for them in the claims ledger read with Get Values.

Put an "Assess this claim" button on the claim detail that runs a background agent. The agent reads the full thread with Get Messages by Conversation, pulls the order with Get Order and the delivery timing with List Fulfillments for Order, checks the customer's prior claim conversations and their prior ledger rows with Get Values, and scores the claim against the stored policy text. It returns a structured assessment: a recommendation of approve, deny or partial; a fit score against the policy; the specific policy clause it relied on; a claim reason category (damaged in transit, defective, wrong item, changed mind, warranty, other); direct quotes from the customer's own messages as evidence; whether the claim is inside or outside the window and by how many days; a suggested resolution of replacement or store credit with an amount; and a repeat claimant flag when this customer has filed the configured number of claims or more, with the count and the dates. The assessment writes back into the app so the queue row and the claim detail both show the recommendation to whoever opens it next. It runs in the background, so the rep keeps working other rows while it finishes and the row shows a pending state until it lands.

The rep makes the real call, never the agent. The claim detail has a decision panel with approve, partial and deny, pre-filled from the recommendation but fully editable, and the rep must be able to disagree and pick a different outcome. Approving with a replacement creates it in Shopify with Create Draft Order against the same customer and line items, then Send Draft Order Invoice so the customer receives the invoice email. Approving with store credit creates the credit with Create Price Rule for the approved amount, then Create Discount Code to generate the code, and shows the rep the code. Partial approvals use the same two paths at a reduced amount. Denying requires the rep to pick or type a denial reason.

Whatever the decision, the app does the same four things. It writes an internal note on the conversation with Create Note by Conversation recording the decision, the policy clause, the agent recommendation, whether the rep followed it, and the resolution issued. It records the reply to the customer on the conversation timeline with Create Message from Conversation. Be precise about that in the UI: creating a Kustomer message records an instance on the conversation timeline and does not itself deliver an outbound email or chat, so label that control as recording the reply on the timeline rather than sending it. It updates the thread with Update Conversation to close it or apply the outcome tag (claim approved, claim denied, claim partial). And it appends a row to the Google Sheets claims ledger with Append Values.

The ledger row carries: decision date, conversation id and link, customer name and email, Shopify order number and order value, delivery date, days since delivery, inside or outside window, claim reason category, agent recommendation, rep decision, whether the rep overrode the agent, resolution type (replacement draft order, store credit, denied, cash refund for finance), claim cost amount, the draft order id or discount code issued, denial reason, deciding rep, and the customer's prior claim count at the time of the decision. Keep one consistent column order so the reporting tab can rely on it, and write the header row if the sheet is empty.

Cash refunds are handed to finance through the ledger. Our Shopify connection has no refund operation, so this app cannot move money back to a card, and it should never imply that it did. When a rep decides a claim deserves cash back, they choose "cash refund, send to finance" as the resolution, and the app records the amount and reason in the ledger row and in the internal note so finance can process it in the payment system. Say that plainly in the interface. The replacement draft order and the store credit code are the two resolutions this app can actually issue.

The second tab is the claims ledger view. It reads the ledger back with Get Values and shows claim cost by month with a trend, claim cost and volume by reason category, claim volume and average cost by deciding rep, approve versus deny versus partial rates, and a repeat claimants table listing the customers with the most claims and the total cost they represent, sorted worst first, so a manager can see who is worth a closer look. Include a date range filter, and let the manager click a repeat claimant to see that person's individual claim rows.

A few rules for how it behaves. Never let a claim be decided twice: once a claim has a ledger row, the queue shows it as decided and the decision panel is read only, showing the outcome and who made it. Show the deciding rep on every decided claim. When no Shopify order matches, still show the row with an unmatched badge and let the rep search Shopify by email or order number from inside the claim. When an order has no fulfillment yet, show "not delivered" instead of a day count. Keep the whole thing fast to work through, because the point is that a rep opens the queue, works top to bottom, and every claim gets the same answer no matter who is on shift.