Return Data Feed

Return data helps TestFreaks understand why customers return products. This data is used in two ways:

  1. Smarter review collection – Return data allows TestFreaks to adjust review invitation emails, including scheduling and triggers, and tailor the questions asked.

  2. Fit & sizing widgets – TestFreaks sizing widgets (True to Size, Runs Small, Runs Large) combine return data with review data to give shoppers accurate fit guidance. By feeding return reasons into our system, the sizing recommendations become significantly more accurate, especially for products with few reviews. Return data also accelerates how quickly we can produce accurate sizing widgets for new products.

Note: Return data is always processed in combination with review data and never displayed directly to end users.

Concepts

Return A record indicating that a product (or an entire order) has been returned by the customer.
Return reason A structured or free-text explanation of why the product was returned. Structured reasons enable automated analysis; free-text reasons provide additional context.
Order-level return A return tied to a specific order and order line, referencing your existing order and product identifiers.
Aggregate return A summary of return statistics for a product over a given time period, useful when individual order-level data is not available.

Data types

TestFreaks accepts return data in two formats depending on what is available in your systems. Choose the one that best fits your setup – each feed should contain only one type of data.

Order-level returns

Order-level returns connect return events to specific order lines. This is the preferred format as it enables the most precise analysis.

Aggregate returns

Aggregate returns provide summarized return statistics per product over a time period. This is useful when your systems do not retain individual return records, or when you want to provide historical data in bulk.

Supported fields

Order-level return fields

Field Description  
order_id The order identifier, matching your Order Feed Required
sku Product ID as it appears in the Product Feed Required
return_date The date the return was registered, in YYYY-MM-DD format Required
reason_code A structured return reason code (see Return reason codes) Optional
reason_text Free-text description of the return reason, as provided by the customer or your system Optional
quantity Number of units returned for this line item. Defaults to 1 if omitted. Optional

Aggregate return fields

Field Description  
sku Product ID as it appears in the Product Feed Required
period_start Start of the period (inclusive), in YYYY-MM-DD format Required
period_end End of the period (inclusive), in YYYY-MM-DD format Required
orders Total number of orders containing this product during the period Required
returns Total number of returned units of this product during the period Required
reason_code A structured return reason code. When used, returns represents the count for this specific reason. Multiple rows with different reason_code values can cover the same product and period. Optional
reason_text Free-text summary for this return reason category Optional

Return reason codes

The following standardized reason codes are supported. You can use these directly, or we can map your internal codes to ours during setup.

Code Description
size_too_small Product was too small
size_too_large Product was too large
wrong_size Wrong size (unspecified direction)
fit_issue General fit issue (not size-related, e.g. cut or shape)
defective Product was damaged or defective
not_as_described Product did not match the description
wrong_product Wrong product was delivered
changed_mind Customer changed their mind
other Other reason (use reason_text for details)

Note: When neither reason_code nor reason_text is provided, the return is still recorded and counted but cannot be used for fit analysis. We recommend including at least reason_code whenever possible.

Feed formats

We accept return data feeds in JSON Lines (recommended), CSV, and JSON format.

JSON Lines (.jsonl) is the preferred format. Each line is a self-contained JSON object, making the files easy to generate, stream, and append to.

Order-level returns

{"order_id":"O123","sku":"P001-02-BLK","return_date":"2024-11-15","reason_code":"size_too_small","reason_text":"Tight around the chest"}
{"order_id":"O124","sku":"P002-M-WHT","return_date":"2024-11-16","reason_code":"changed_mind"}
{"order_id":"O125","sku":"P001-02-BLK","return_date":"2024-11-17","reason_code":"defective","reason_text":"Broken zipper on arrival"}

Aggregate returns

{"sku":"P001-02-BLK","period_start":"2024-11-01","period_end":"2024-11-30","orders":320,"returns":45,"reason_code":"size_too_small"}
{"sku":"P001-02-BLK","period_start":"2024-11-01","period_end":"2024-11-30","orders":320,"returns":12,"reason_code":"size_too_large"}
{"sku":"P001-02-BLK","period_start":"2024-11-01","period_end":"2024-11-30","orders":320,"returns":8,"reason_code":"defective"}
{"sku":"P002-M-WHT","period_start":"2024-11-01","period_end":"2024-11-30","orders":150,"returns":5}

CSV

Order-level returns

order_id,sku,return_date,reason_code,reason_text,quantity
O123,P001-02-BLK,2024-11-15,size_too_small,"Tight around the chest",1
O124,P002-M-WHT,2024-11-16,changed_mind,,1
O125,P001-02-BLK,2024-11-17,defective,"Broken zipper on arrival",1

Aggregate returns

sku,period_start,period_end,orders,returns,reason_code,reason_text
P001-02-BLK,2024-11-01,2024-11-30,320,45,size_too_small,
P001-02-BLK,2024-11-01,2024-11-30,320,12,size_too_large,
P002-M-WHT,2024-11-01,2024-11-30,150,5,,

JSON

Order-level returns

{
  "returns": [
    {
      "order_id": "O123",
      "sku": "P001-02-BLK",
      "return_date": "2024-11-15",
      "reason_code": "size_too_small",
      "reason_text": "Tight around the chest"
    }
  ]
}

Aggregate returns

{
  "returns": [
    {
      "sku": "P001-02-BLK",
      "period_start": "2024-11-01",
      "period_end": "2024-11-30",
      "orders": 320,
      "returns": 45,
      "reason_code": "size_too_small"
    }
  ]
}

Feed delivery

Return data feeds use the same delivery methods as other TestFreaks feeds.

As a file

TestFreaks can fetch return data feeds from URLs on https:// or sftp://.

You can also schedule daily or weekly feed uploads to TestFreaks using SFTP after setting up an account with us.

Return data feed filename

The name of each file should contain the feed type, client ID and date.

For example:

returns-example.com-en-2024-11-20.jsonl
returns-example.com-en-2024-11-20.csv

Checklist

  • Does the feed include product identifiers (sku) matching your Product Feed?
  • For order-level returns, does it reference order_id values from your Order Feed?
  • Are return reason codes included? These are essential for fit & sizing analysis.
  • Is the feed updated regularly (daily or weekly)?
  • Can you provide historical return data for seeding? Even aggregate data for the past 6-12 months significantly improves sizing accuracy from day one.