Disposition data

Disposition data is what your warehouse records about a returned item once it physically arrives: what condition it was in, and what was done with it. It's the single most valuable training signal Pinch uses to detect abuse — every other signal (variables, identity graph, workflows) gets sharper when disposition data is flowing through.

A return where the customer claimed "damaged on arrival" but the warehouse logs NEW condition is a strong abuse signal. The same return with no disposition data is just a refund. Pinch can score a customer without it, but accuracy meaningfully improves when warehouses record what they're seeing.

The standard template

This is the full set of fields Pinch's models are trained on. Send this and the abuse-detection accuracy is at its highest.

For each returned line item:

Field	Type	Description
returnId	string	The return identifier the item belongs to.
lineItemId	string	The line item this disposition refers to.
returnedItemState	enum	Condition the item was in when received at the warehouse.
dispositionOutcome	enum	What the warehouse did with the item.
processedAt	timestamp	When the warehouse processed this item.
notes	string	Free-form notes from the warehouse operator (optional).

returnedItemState values

Value	Meaning
NEW	Item arrived in original, sellable condition — tags on, packaging intact.
OPEN_BOX	Packaging opened but item itself is unused and sellable.
LIGHTLY_USED	Visible wear consistent with try-on or short use — usually not resellable as new.
HEAVILY_USED	Significant wear, washing, or damage from use.
DAMAGED_ITEM	Item damaged in a way inconsistent with normal use (broken, stained, torn).
EMPTY_BOX	Customer returned packaging only — no item inside.
COUNTERFEIT_ITEM	Item returned is not the genuine product that was shipped.
LOST_ITEM	Item did not arrive at the warehouse.

dispositionOutcome values

Value	Meaning
RESTOCK	Item went back into sellable inventory.
REFURBISH	Item needed repair/cleaning before going back to sellable.
LIQUIDATE	Item sold off via secondary channel (outlet, B-stock).
DONATE	Item donated.
RECYCLE	Item recycled.
REMOVE_OTHERS	Item removed from inventory for non-abuse reasons.
REMOVE_SUSPECT_ABUSE	Item removed and flagged as abuse-suspected by the warehouse team.

Fidelity levels Pinch can work with

Not every merchant can send the full template on day one. Pinch can work with three tiers of disposition data — abuse detection accuracy is highest at the top and falls off as fewer fields are sent.

Level	What you send	What Pinch can do with it
Full set (highest fidelity)	The standard template above — returnedItemState and dispositionOutcome per line item, plus timestamps and notes.	Full abuse-type detection (Wardrobing, Empty Box, Switch Fraud, etc.) and full warehouse-outcome learning.
Damaged / not damaged at item + return level (middle fidelity)	A boolean flag per returned item indicating whether the item arrived damaged or in unsellable condition, scoped to both the item and the parent return. No detailed condition enum, no outcome.	Coarse abuse detection — Pinch can identify customers who systematically return damaged items, but loses signal on subtler patterns like wardrobing or empty-box claims.
Restock / no restock only (lowest fidelity)	A single boolean per returned item: did it go back into stock, or didn't it?	Pinch can learn which customers' returns systematically don't restock — a useful but coarse abuse proxy. Detailed abuse-type classification isn't possible.

The standard onboarding path is to start at whatever fidelity your warehouse already records, then move up. Most merchants begin at the middle tier with their RMS auto-syncing damaged/not-damaged, and graduate to the full template within 1–3 months as the warehouse team starts logging condition codes.

How to send disposition data to Pinch

Three options, in order of how most merchants use them:

1. Auto-sync from your RMS — Aftership, Loop, and Narvar all support condition codes that Pinch maps to returnedItemState. If you're on one of these, the sync runs automatically once the integration is connected.
2. CSV upload — Drop a CSV in the dashboard for a backfill or recurring batch. The expected columns match the standard template.
3. Disposition API — POST /v1/disposition from your WMS or warehouse software. Same shape as the standard template, one POST per disposition event.

Your customer success manager will help you pick the lowest-friction option for your warehouse setup during onboarding.

See also

• Pinch concepts — how disposition feeds variables, workflows, and the Pinch Assessment
• Integrations: Returns systems — RMS connectors that auto-sync disposition
• Send a Disposition — the REST endpoint