Item Grading and Dispositioning


Loop's item grading and dispositioning feature allows merchants to review data about returned items' conditions and final outcomes. Combining this data with the return item state from the warehouse inspection gives merchants benefits including:

  • Reduction of returns fraud through easier spotting of deceitful shoppers.
  • Improved product lifecycle through identification of items with manufacturing issues.
  • A centralized view in Loop admin of the returned items, return reason(s), and item condition(s).

Important: To use this feature, merchants must use an integrated warehouse partner.

In this article:

How it works

Loop uses two API endpoints to gather returns data from a merchant's logistics partner such as a warehouse management system (WMS) or third-party logistics (3PL) provider. For this feature, the data includes:

  • Item grade (the condition of a returned item):
    • Excellent
    • Needs some work
    • Damaged
  • Disposition outcome (the final state of the returned item):
    • Restock
    • Donate
    • Recycle
    • Refurbish
    • Resell

The points below describe how this data gathering is possible:

  1. The merchant generates an API key for their logistics partner, who will make API calls. Depending on the company, the merchant's logistics partner may be an internal developer, a third-party agency, or a technical employee for the 3PL.
  2. The logistics partner makes a call to Loop's item grade or disposition API for each line item, or each product in the return.

    Important: the line item IDs in the API request must belong to an order for the shop that the API key belongs to.

  3. The line item's grade or disposition data appears in the return detail view, as pictured below.

    The black shirt being returned has an item grade (condition) of Grade A, and a disposition (outcome) of "Ready to resale."


Generate an API key in the Loop admin for the company's logistics partner.

Important: Be sure to select "Returns" as a scope for the API key. Merchants may select others, but Returns is particularly necessary for this feature to work.

"Generate API key" pop-up with Return scope and Generate button.

The company's logistics partner is now ready to make calls to Loop's item grade and disposition APIs!

Note: The logistics partner must make a call per line item (product in the return) that they are grading or dispositioning.

Viewing the data

Review the below section(s) for instructions on viewing item grade and disposition data, depending on the information needed.

For a single return

To view the grade and disposition data collected by Loop's APIs:

  1. Open Loop admin.
  2. Search for and click on the relevant return.
  3. On the return details page, find the item grade or disposition outcome for each product, as pictured under How it works.
  4. Click "View full warehouse item details" for more data sent for the line item(s) from the APIs.

    "View full warehouse item details" button on an example return details page.

Note: Only "Description" is required in the returned data sets, so other fields (refer to the below screenshot) may appear blank based on what the APIs send back.

Additional processing details for a return including inspection date, item condition, description, operator, and notes.

In aggregate

Merchants can also review and export item grade and disposition data in aggregate:

  1. In Loop admin, go to Analytics > Reports.

    View of the Analytics menu in Loop Admin.
  2. Find the Warehouse & Shipping section, then click "Grading and disposition".

    View of Warehouse & Shipping section on Loop admin Reports page, with star next to "Grading and disposition".
  3. Set the export file type and returns time range needed.

    View of "Grading and disposition" page with file type options and date range field.

The data can now act as a guide to set an outcome for this return!

Workflows addition

Merchants can also use item grade data in their Workflows to reduce losses and prevent fraud. For example, these API insights can show if a shopper consistently returns empty boxes, incorrect items, and damaged items. If the shopper returned three items in damaged condition this month, the merchant can set the workflow outcome so that new returns from that shopper are flagged for review!

Refer to Loop's Workflows Tiers article to confirm which Loop plans include Advanced Workflows. Certain tiers allow merchants to create workflow conditions based on item grade data.

If the company's Loop plan includes Advanced Workflow options, continue below to set up conditions:

  1. In Loop admin, click on Settings > Workflows.
  2. Click on Create Workflow.

    "Create workflow" button at top of Workflows page in Loop admin.
  3. While creating a condition (refer to Loop's Workflows article for help), choose Customer > Return count with missing or incorrect items.

    Note: This count triggers when a line item’s condition_category is recorded in the API call with one of these values:

    1. incorrect_item
    2. missing
    3. junk
  4. Choose the Month and Amount that will trigger this condition.

    Condition with Category "Customer - Return count with missing or incorrect items", Month(s) "3 Months", and Amount "is greater than 3".

    Add the condition (refer to the screenshot above, at the bottom).

    Choose the return outcome.

    Return outcome of "Manual review" in Loop admin's Workflows feature.

    Recommended outcomes from Loop include:

    1. Set up for manual review.
    2. Limit return bar drop-offs, as processing for return bars must be at a drop-off location.
    3. Charge a handling fee.
    4. Limit refunds.
  5. Publish the workflow.

For questions about your Loop plan or workflow options, please reach out to your Merchant Success Manager (MSM).

Plan information

The pricing and packaging for this feature is split in two, as shown below:

  • Item grade and disposition API endpoints:
    • Flat-fee + Integrations add-on
    • Usage-Based Essentials
  • Associated Workflows for fraud reduction:
    • Flat-fee + Custom Rules add-on
    • Usage-Based Advanced

Tip: This means that a merchant can access item grade and disposition data in Loop if they only have access to Loop's API. However, to use that data to create Workflows for future returns, the merchant must have Advanced Workflows access.

Please review Loop's Pricing page for more information.


Does this feature work for merchants that are self-fulfilling? Yes! Merchants can integrate and call the item grade and disposition APIs themselves if they have a technical team or can outsource this work. Note that there is no UI in the Loop admin to input this data; it is only writeable from the APIs.

What if the 3PL is connected via an integration platform as a service (iPaas)? If the iPaas has updated to map from the 3PL’s APIs to Loop’s item grading and dispositioning APIs, this feature should work and enable all the Loop admin scenarios, too.

Is the Workflow condition based on items or returns? While the item grade is captured at the item level, the workflow condition works at the return level.

Are there Workflows conditions for items that come back in "poor" condition? Not yet. However, merchants now have a central view of their returns data, which they can use to better identify abusive returners! They can add to this by using the Customer Workflow condition for fraud reduction tactics.

What else can I do about serial or abusive returners? Loop suggests the following:

  • Limit refunds and only allow exchanges or store credit for serial returners.
  • Place abusive returners on a blocklist.
  • Add a photo upload.
  • Charge handling fees.
  • Reduce bonus credit.

How can I connect all the different parties involved in making this happen? Set up a meeting with Loop and your 3PL to discuss building into the new API endpoints.

What if I don't have the right Loop plan for Advanced Workflows? Discuss your current Loop plan with your MSM to ensure eligibility for this fraud-reducing tactic.

Please reach out to with any additional questions.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.