Grading process

The grading process begins once the warehouse operations team completes the validation of returned items. This step involves a detailed inspection to assess the condition of each product returned by the customer. Based on predefined criteria—such as packaging integrity, signs of usage, and overall product functionality—the warehouse team assigns a status or grade to each item. These results are then sent back to iF returns, enabling the next steps in the return flow, such as issuing refunds, creating exchange orders, or restocking depending on the item's condition.

Grading API

iF returns exposes an API designed to receive and process the results of item validations performed by the warehouse upon receiving customer returns. For each returned item, the API accepts a status indicating its condition (e.g., "resellable", "damaged", "missing parts"), along with additional metadata related to the grading process. This includes timestamps for when the validation took place and optional notes containing detailed observations from the warehouse team. The API ensures that all grading data is recorded accurately and can be seamlessly integrated into downstream processes such as refunds, inventory updates, or customer notifications.

To support seamless integration with existing warehouse systems, the Grading API is designed to accept multiple payload formats. This flexibility allows the API to ingest validation data that may already be generated by the warehouse as part of their current workflows. Instead of requiring custom data transformation or new logic, the API can process these existing payloads directly to record the grading results. This approach minimizes development effort, accelerates implementation, and ensures compatibility with diverse operational setups.

Payload - Only Registered Items

This is the standard payoload supported by the grading API. This payload only accepts the validation status for the items that were included in the return requested by the customer in the portal. The definition of this payload could be found in the API specification section for the Grading endpoint

Request

{
  "shopCode": "marchelacolombine",
  "shipmentId": "R1-64231",
  "shipmentIdType": "RETURN_NAME",
  "status": "OK",
  "itemsWithIncidents": [
    {
      "barcode": "8893892",
      "sku": "1234567",
      "status": "OK-NEEDS-REFITTING",
      "note": "picking error",
      "validatedAt": "2022-11-17 12:01:00Z"
    },
    {
      "barcode": "8893892",
      "sku": "1234567",
      "status": "OK-NEEDS-REFITTING",
      "note": "picking error",
      "validatedAt": "2022-11-17 12:01:00Z"
    }
  ]
}

Response

{
  "statusCode": "200",
  "description": "Your grading have been received correctly"
}

Payload - New Items

This endpoint was deigned to support scenarios where warehouse teams validate items that were not originally included in a customer's return request submitted via the portal. This includes two key scenarios:

• Items from an existing order that were not selected during the return initiation process.
• Items associated with orders for which no return request was opened at all.

The API's supports these use cases by allowing the submission of grading data independently of the original return request. Payload must include sufficient context to identify the new items typically through fields like SKU or order name. This ensures the system can accurately associate and store grading results, even in non-standard return scenarios, maintaining data consistency and enabling downstream actions like refunds or inventory updates.

Path Parameter

The endpoint requires as a mandatory parameter the name of the ecommerce order to which the validated items belong. This parameter must be sent as part of the URL:

/orders/{order_name}returns_gradings

Request

{
  "shopCode": "mystore",
  "returnName": "RMA7854",
  "returnLineItems": [
    {
      "sku": "1234567",
      "status": "APPROVED",
      "note": "",
      "validatedAt": "2022-11-17 12:01:00Z",
      "refundType": "ORIGINAL_PAYMENT_METHOD"
    },
    {
      "sku": "1234567",
      "status": "REJECTED",
      "note": "",
      "validatedAt": "2022-11-17 12:01:00Z",
      "refundType": "ORIGINAL_PAYMENT_METHOD"
    }
  ]
}

The request payload contains the following fields:

The grading API will execute the following steps to process the requestpayload:

• Step 1: Get the details of the order from the eCommerce using the “orderName”. If more than one order exists with the same name, the oldest one will be considered.

• Step 2: Get the list of return requests already created in iF Returns for the order “orderName”:

  • Step 2.1: If there are no return requests for the order (only return requests with a status different from DISCARDED or CLOSED will be considered), the following actions will be taken:

    • A new return will be created in iF Returns, by adding all the return line items reported in the payload.
    • The result obtained from step 1 will be used to: (1) check all reported items exist in the eCommerce order and are available for return (2) complete all data required for registering the new items in iF returns.

  • Step 2.2: If there are return requests for the order (again, only those with a status different from DISCARDED or CLOSED will be considered), the following actions will be taken:

    • It will match the graded items included in the payload with the items included in the return requests retrieved from iF Returns.
    • If an item does not exist in any request, it will be added in the first request with a status other than DISCARDED or CLOSED, where there was a match with the reported items.
    • The result obtained from step 1 will be used to: (1) check the added items exists in the eCommerce order and is available for return (2) complete all data required for registering the new item in iF returns.

• Step 3: Once the grading API has processed all the items received in the payload, it will call the eCommerce endpoint to:

  • Step 3.1: Create a new return in the eCommerce for all items not included in the return requests registered in iF Returns.

  • Step 3.2: Execute the corresponding resolution for all the reported Items.

  • Step 3.3: Close the associated eCommerce returns.

Response

{
  "statusCode": "200",
  "description": "Your grading have been received correctly"
}

The response payload can return the folling codes: