v1.033

Returns now show what the warehouse reported finding in the parcel.
When a returned parcel holds something you never sent, such as a counterfeit, a substitute item or nothing at all, the warehouse reports it and disposes of it. These reports were not visible through the API until now. GET /v1/integrations/returns-list, GET /v1/integrations/returns and the Return status change webhook now include them on every return.

🚀 New Endpoints

None

🛠 Schema & Property Updates

Reported Units on Returns

Both fields are added to the return object (ReturnOutput), which is shared by GET /v1/integrations/returns-list, GET /v1/integrations/returns and the Return status change webhook (returnStatusChange). They are always present: an empty array and null when nothing was reported.

• fraudulent_units (array) - Units the warehouse found in the return that you never sent, in the order they were reported. They are not listed under items, because they match no item of the return and do not change any item's received_quantity. Each entry contains:
  • unit_uuid (string) - UUID of the reported unit.
  • classification (string) - fraudulent for an item that is not yours, such as a counterfeit or a substitute, or unknown_merchant_item for an item that may be yours but was not part of this return.
  • final_disposition (string) - What happened to the unit. Reported units are disposed of, so this is dispose.
  • received_at (string, date-time) - When the warehouse finished reporting the unit at the grading station.
• empty_package_report (object|null) - Present when the warehouse reported that the return package arrived with nothing in it:
  • unit_uuid (string) - UUID of the unit that records the empty package.
  • reported_at (string, date-time) - When the warehouse reported the package as empty and disposed of it.

A report appears only after the warehouse has finished handling it. A report that is withdrawn as a correction disappears from both fields.

Enums

• FlaggedUnitReportClassification: New enum with the values fraudulent and unknown_merchant_item, used by fraudulent_units[].classification.

Return-to-Merchant Disposition on Unit Records

• items[].receiving_details[].final_disposition (string|null) - a return_unit record of a unit the warehouse decided to return to you now reports return_to_merchant, the value a receive record of such a unit already reports. It used to report other. This affects only historical records that originated from the legacy Optoro flow.

📦 New Support Schemas

The following schemas were introduced to support reported units on returns:

• ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnFraudulentUnitPublicApiOutput
• ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnEmptyPackageReportPublicApiOutput
• ShipMonk_Warehouse_Returns_Enum_FlaggedUnitReportClassification

📖 Documentation & Constraints Changes

None

No endpoints, fields or enum values were removed. Both new fields are additions to the response and the webhook payload, and return_to_merchant was already a documented final_disposition value, so this version is backward-compatible. Clients that reject unknown properties must accept the two new fields.