Send Disposition Data

Call /v1/return/disposition/{return-id} after your warehouse has inspected the returned items and decided what to do with them. The condition and outcome data Pinch receives here is the single highest-value training signal for the abuse-detection model — it's the only way Pinch can confirm whether the customer actually returned what they claimed, in the condition they claimed.

If you're on Shopify with Aftership for returns, this data syncs automatically. For custom integrations or other warehouse systems, send it via this API.

Request

POST /v1/return/disposition/{return-id} HTTP/1.1
Host: api.pinch.ai
Authorization: {api-key}
Content-Type: application/json

The {return-id} in the path is your providerReturnId from the original /v1/return call.

Body

Field	Type	Required	Description
itemDispositions	array	yes	One entry per inspected item. See below.

Item disposition entry

Field	Type	Required	Description
identifierType	string	yes	UPC, EAN, JAN, SKU, SerialNo.
identifier	string	yes	The actual identifier value. Must match an item on the original return.
returnedItemCondition	string	yes	Condition of the item as received. Enum below.
dispositionOutcome	string	yes	What you did with the item. Enum below.
returnMethod	object	no	{ "returnMethod": "PICKUP" | "DROPOFF" | "IN_STORE" }.
refundMode	object	no	{ "refundMode": "CASH" | "STORE_CREDIT" | "ORIGINAL_PAYMENT" | "EXCHANGE" }.
warehouseIdentifier	string	no	Your warehouse ID for the inspection location.
storeIdentifier	string	no	For in-store returns, the receiving store ID.
images	array of strings	no	URLs of photos taken during inspection. Useful for disputes.
inspectionNote	string	no	Free-text inspector comment. Pinch reads these to refine the model.

returnedItemCondition enum

Value	Meaning
NEW	Item came back unused, original packaging intact, salable as new.
OPEN_BOX	Packaging opened but item appears unused.
LIGHTLY_USED	Visible signs of use; not new but functional and refurbishable.
HEAVILY_USED	Significant wear; only salvageable for parts or liquidation.
EMPTY_BOX	Box arrived without the item inside. Strong abuse signal.
COUNTERFEIT_ITEM	Returned item is a knockoff or different from what was shipped. Strong abuse signal.
DAMAGED_ITEM	Item arrived damaged (could be carrier damage, not abuse).
LOST_ITEM	Return shipment lost in transit.

dispositionOutcome enum

Value	Meaning
RESTOCK	Item returned to sellable inventory at full price.
RESTOCK - SALE/CLEARANCE	Restocked but discounted (open-box, lightly used).
RECYCLE	Disposed of through a recycling stream.
REFURBISH	Sent to a refurb partner for repair before resale.
DONATE	Donated to a charity partner.
LIQUIDATE	Sold to a wholesale liquidator.
REMOVE_OTHERS	Disposed of for non-abuse reasons.
REMOVE_SUSPECT_ABUSE	Disposed of because the return was an abuse case (empty box, counterfeit, etc.).

REMOVE_SUSPECT_ABUSE paired with EMPTY_BOX, COUNTERFEIT_ITEM, or repeated HEAVILY_USED from the same customer is the strongest signal Pinch uses to confirm abuse.

Example request

curl

curl "https://api.pinch.ai/v1/return/disposition/WETIIO2PG" \
  -H "Authorization: $PINCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "itemDispositions": [
      {
        "identifierType": "SKU",
        "identifier": "TF-2157TF72-100",
        "returnedItemCondition": "LIGHTLY_USED",
        "dispositionOutcome": "RESTOCK - SALE/CLEARANCE",
        "returnMethod": { "returnMethod": "PICKUP" },
        "refundMode": { "refundMode": "ORIGINAL_PAYMENT" },
        "warehouseIdentifier": "wh-east-1",
        "images": ["https://yourcdn.com/inspections/img-001.jpg"]
      },
      {
        "identifierType": "SKU",
        "identifier": "TF-5121TF72-100",
        "returnedItemCondition": "EMPTY_BOX",
        "dispositionOutcome": "REMOVE_SUSPECT_ABUSE",
        "warehouseIdentifier": "wh-east-1",
        "inspectionNote": "Box weight matched empty packaging; no item present.",
        "images": ["https://yourcdn.com/inspections/img-002.jpg"]
      }
    ]
  }'

Node

await fetch(`https://api.pinch.ai/v1/return/disposition/${returnId}`, {
  method: "POST",
  headers: {
    Authorization: process.env.PINCH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    itemDispositions: [
      {
        identifierType: "SKU",
        identifier: "TF-2157TF72-100",
        returnedItemCondition: "NEW",
        dispositionOutcome: "RESTOCK",
        warehouseIdentifier: "wh-east-1",
      },
    ],
  }),
});

Python

import os, requests

requests.post(
    f"https://api.pinch.ai/v1/return/disposition/{return_id}",
    headers={
        "Authorization": os.environ["PINCH_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "itemDispositions": [
            {
                "identifierType": "SKU",
                "identifier": "TF-2157TF72-100",
                "returnedItemCondition": "NEW",
                "dispositionOutcome": "RESTOCK",
                "warehouseIdentifier": "wh-east-1",
            }
        ]
    },
)

Response

200 OK with a confirmation envelope:

{
  "providerReturnId": "WETIIO2PG",
  "pinchReturnId": "pret_3f8a1c",
  "dispositionsRecorded": 2,
  "modelImpact": "queued"
}

Field	Description
dispositionsRecorded	Count of items accepted in the payload.
modelImpact	queued if the disposition is being incorporated into the model; applied if effects are immediate.

This endpoint doesn't return a decision — disposition is reporting, not gating.

When to send

There are three reasonable patterns:

Pattern	When	Trade-off
Per-item, real-time	As each warehouse inspector clears an item	Highest data freshness; needs warehouse system integration
Per-return, on completion	After all items on a return are inspected	Simpler; usually a few hours after the return is received
Batch upload	Daily or weekly CSV via the dashboard	Easiest; lower data freshness

If your warehouse system can webhook out on inspection completion, the per-return pattern is the right starting point.

CSV upload alternative

If you can't hit the API directly, the dashboard's Integrations → Warehouse System → Upload Disposition Data page accepts a CSV with the same schema. Download the template, fill it out, upload. Schedule it weekly via cron until you can ship API integration.

Errors

HTTP	Code	Meaning
400	invalid_request	Required field missing
404	return_not_found	The {return-id} in the path doesn't exist
422	unknown_enum_value	returnedItemCondition or dispositionOutcome not in the enum
422	item_not_on_return	identifier doesn't match any item on the original return

See also

• Return API — must be called first to register the return
• Disposition data guide — why disposition matters, longer-form
• Aftership integration — auto-sync from Aftership Restocking