Returns Hooks

The Returns app fires a single custom hook, OnClaimResolve, that other apps and the merchant's own rules can listen to in order to apply the actual side effects of a resolved claim — refunds, replacements, compensations, emails, and so on.

OnClaimResolve

Fired with the lines of a claim that have just been resolved. The hook is the integration point between the Returns app's UI/state model and any business-specific behavior that should happen when a claim line is accepted.

When It Fires

OnClaimResolve is fired from two places:

• At claim completion — for every completed claim line where requireInspection is not true. These lines are resolved immediately, with acceptedQuantity equal to the claim line's quantity.
• At RMA completion — for every RMA line where acceptedQuantity > 0. The resolution is taken from the originating claim line, and acceptedQuantity reflects the inspected value.

If an RMA has no claim relation, OnClaimResolve is not fired for that RMA.

Hook Input

The hook payload has the shape:

{
  hook: 'OnClaimResolve'
  claimId: uuid
  orderId: uuid | nothing
  lines: [{
    claimLineId: uuid
    resolution: text
    orderLineId: uuid | nothing
    acceptedQuantity: number
    productNumber: text | nothing
    metadata: { text -> value }
  }]
}

Field	Notes
claimId	ID of the resolving claim.
orderId	ID of the connected order, or nothing if the claim has no order relation (rare).
lines[].resolution	Resolution key from enums/graph/ticket.claim.line/resolution/values/* — see Resolution Types.
lines[].orderLineId	Matched order line, or nothing for lines that were not (or could not be) matched. Many resolution types only make sense when this is set.
lines[].acceptedQuantity	The quantity actually being resolved. For non-inspected lines this equals the claim line's quantity; for inspected lines it's whatever the warehouse accepted.
lines[].productNumber	The product number on the claim line. May differ from the order line's product number if the line was created without one.
lines[].metadata	All dynamic fields on the claim line whose key matches metadata_*, including the prefix. Resolution-specific custom-field values live here — see Resolution Types.

refundFactor is not on the hook

For lines that required inspection, the inspected refundFactor is already applied to the resulting return on the connected order. For lines that didn't require inspection, the hook listener is free to emit createReturn with whatever factor is appropriate for that resolution. Either way, refundFactor is not carried on the hook payload.

Listening Rule

Rules listen by declaring param input with hook: 'OnClaimResolve' and the fields they need:

param input: {
  hook: 'OnClaimResolve'
  claimId: uuid
  orderId: uuid | nothing
  lines: [{
    claimLineId: uuid
    resolution: text
    orderLineId: uuid | nothing
    acceptedQuantity: number
    productNumber: text | nothing
    metadata: { text -> value }
  }]
}

import 'iterators'

// Emit a 100%-discount per claim line resolved as 'compensateFull'
from
  input.lines
  where l => l.resolution == 'compensateFull' and l.orderLineId is uuid
  select l => {
    effect = 'orderCommand'
    type = 'createStaticOrderLineDiscount'
    orderLineId = l.orderLineId
    isPercentage = true
    value = 1
    description = 'Claim compensation'
  }

TIP

You only need to declare the fields your rule actually uses. Filtrera's structural type system matches the rule's input shape against the hook payload.

Supported Effects

The Returns app dispatches the following effect types emitted by hook listeners:

Effect	How it's applied
orderCommand	Applied to the connected order in a single transactional batch with any other orderCommand effects from the same hook invocation.
messageActor	Emitted as-is. Useful for creating replacement orders, posting messages to other tickets, etc.
sendEmail	Emitted as-is.
scheduleJob	Emitted as-is.
validationError	Emitted as-is.

Any other effect type is emitted as-is.

Idempotency

OnClaimResolve is delivered at most once per claim line: at claim completion (if no inspection is required) or at RMA completion (if inspection was required and the inspector accepted some quantity). Rules listening to the hook do not need to deduplicate.

See Also

• Resolution Types — Defining custom resolution types and their per-resolution custom fields.
• Returns Graph — Ticket types and fields involved.
• triggerHook Reference — How custom hooks work.
• Rule Effects — Available effect types.