Returns App

The Returns app provides customer-claim and warehouse-inspection workflows for Hantera. It models two related but independent ticket actor types — claim and rma — and exposes resolution-time effects through the OnClaimResolve custom hook.

What It Provides

HTTP Ingresses

Public endpoints for filing and listing claims:

Endpoint	Purpose
POST /ingress/returns/claims/create	File a new claim for an order, with one or more claim lines
GET /ingress/returns/claims/get-by-order	List all claims attached to a given order

See API Reference for full request/response schemas.

Graph Nodes & Edges

The app contributes four ticket-derived node types and their sets/edges:

• ticket.claim / set claims / edge claim
• ticket.claim.line / set claimLines / edge claimLines
• ticket.rma / set rmas / edge rma
• ticket.rma.line / set rmaLines / edge rmaLines

Together with enum value sets for tags, reject reasons, claim-line state, and resolution. See Graph.

Custom Resolution Types

Resolution types — refund, replace, compensate, or anything else an app or merchant wants to define — are entirely registry-driven. Each resolution is a value-set entry under enums/graph/ticket.claim.line/resolution/values/ and may declare a set of per-resolution custom fields under apps/returns/claims/fieldDefinitions/line/. Field values are surfaced on the OnClaimResolve hook for the hook listener to act on. See Resolution Types.

Portal Extension Points

Slots and services exposed for other apps to extend the claim and RMA views:

• Four slots for adding sections to the claim and RMA summary and line panels
• Two services for contributing warnings to the claim and RMA headers

See Portal Extensions.

Lifecycle

RMAs can stand alone

The app creates an RMA automatically when a claim line's resolution requires inspection, but RMAs are designed to track a returned product on their own and do not require an originating claim. Other apps or flows may create RMA tickets directly.

Key Features

• Public HTTP ingresses for creating and listing claims, with automatic order-line matching by product number and remaining claimable quantity
• Four ticket-backed graph node types (ticket.claim, ticket.claim.line, ticket.rma, ticket.rma.line) with their fields, edges, and customizable enum value sets — see Graph
• OnClaimResolve custom hook — fired for non-inspected lines at claim completion and for inspected lines at RMA completion. orderCommand effects are applied to the connected order in a single batch — see Hooks
• Registry-driven resolution types — define new resolution types by adding enums/graph/ticket.claim.line/resolution/values/<key> entries with requireInspection / requireInspectionEditable properties, and attach per-resolution custom fields via apps/returns/claims/fieldDefinitions/line/<key> entries — see Resolution Types
• Stand-alone RMAs — RMA tickets can track returns without an originating claim, allowing other flows (e.g. inventory or recall workflows) to drive the inspection-and-refund loop
• Portal extension points — four slots and two warning services on the claim and RMA views — see Portal Extensions