Returns API Reference
The Returns app exposes public HTTP ingresses for claim management. All endpoints are prefixed with /ingress/returns/.
Metadata convention
Both endpoints follow the metadata_ prefix convention: keys you pass under metadata on createClaims are stored as dynamic fields named metadata_<key>, and getClaimByOrder strips the prefix back off when returning them. The same prefixed keys are surfaced on the OnClaimResolve hook.
Create Claim
Creates a new claim ticket for an existing order, with one or more claim lines. Each line is matched against an order line (either by explicit orderLineId or by auto-matching on productNumber, taking into account quantities already claimed or returned). Lines that cannot be matched are still created but without an orderLine relation.
Metadata keys supplied on the claim or on individual lines are stored as dynamic fields prefixed with metadata_. Those same keys are exposed back without the prefix via Get Claims by Order and on the OnClaimResolve hook payload.
The claim's channelKey is automatically copied from the connected order.
Request Body
Responses
Claim created. The body is the result of the underlying messageActor call on the new claim ticket.
Samples
Get Claims by Order
Returns all claims attached to the given order, including their claim lines with metadata, pictures, and the matched order-line relation.
Dynamic fields stored on the claim or its lines with a metadata_ prefix are returned under metadata with the prefix stripped.
Parameters
Query Parameters
The order ID.
"uuid"Responses
Array of claims for the order.
Samples
Order-Line Matching
createClaims accepts an optional orderLineId per line. When omitted, the ingress auto-matches lines against the connected order's order lines using the following predicate:
ol.productNumber == line.productNumber
AND
ol.quantity >= (approvedClaimedQuantity + returnedQuantity + lineQuantity)Where approvedClaimedQuantity is the sum of quantities from claim lines on this order line whose claim is already in the completed state. Lines that cannot be matched are still created — they just lack an orderLine relation, which is also valid for some resolution types (see Resolution Types).
Error Codes
| Code | Endpoint | Meaning |
|---|---|---|
NOT_FOUND | both | The referenced orderId does not exist or the caller lacks access to it. |
QUERY_ERROR | getClaimByOrder | The underlying graph query failed. The original error is included in message. |