Returns

The return object — every field, which ones are nullable, and the casing inconsistency to watch for.

The return object

A return tracks merchandise coming back to a merchant. It carries the RMA, the reason, the condition of the goods, and the refund amounts, with a line item per SKU returned.

Almost every field is nullable. A freshly created return typically has rma, order_id, customerEmail, status, and created_date populated and everything else null — including amount, total_refunded, condition, and reason_category. They fill in as the return is processed.

Write your integration to expect nulls on every optional field rather than only on the ones that look optional. This is the single most common source of breakage against this object.

Casing

The object mixes two conventions, and the API sends them exactly as written:

Field	Note
customerEmail	camelCase
enteredBy	camelCase
everything else	snake_case

Do not normalise these when serialising a request, and do not assume a snake_case equivalent exists. customer_email is not a field.

Return

Name	Type	Description
id	Integer	Unique identifier for the return
rma	String	Return Merchandise Authorization number, e.g. #1014-R5
status	String	Current state, as a short code — see Status
created_date	Date/Time	When the return record was created
order_id	Integer	The order being returned against
order_date	Date/Time	When that order was originally placed
customer_id	Integer	The customer returning the goods
customerEmail	String	Customer email (camelCase)
enteredBy	String	Who created the record (camelCase)
requested_date	Date/Time	When the customer requested the return
shipped_date	Date/Time	When the goods were shipped back
tracking_number	String	Inbound tracking number
reason_category	String	Why it is coming back — see Reasons
reported_condition	String	Condition as the customer described it
condition	String	Condition as assessed on receipt
description	String	Free-text detail
serial_number	String	Serial number of the returned item
amount	Decimal	Monetary amount associated with the return
total_refunded	Decimal	Total refunded, including tax
tax_refunded	Decimal	The tax portion of the refund
flat_rate_shipping	Boolean	Whether return shipping is charged at a flat rate
action_needed	Boolean	Whether the return is waiting on a human
return_line_items	Array	The items — see below

reported_condition and condition are deliberately separate. The first is the customer’s claim, the second is what your team found. A discrepancy between them is exactly the signal worth reporting on — and collapsing them into one field destroys it.

Return line item

Name	Type	Description
id	Integer	Unique identifier for the line item
return_id	Integer	The parent return
sku	String	SKU of the returned item
name	String	Item name or description
price	Decimal	Unit price
amount	Decimal	Amount for this line
condition	String	Condition of this specific item
serial_number	String	Serial number for this item
tax_refunded	Decimal	Tax refunded on this line
flat_rate_shipping	Boolean	Flat-rate shipping on this line

A return can have an empty return_line_items array. A return created from a customer request before the goods arrive has no lines yet — do not treat an empty array as an error.

Status

status is a short code, not a word. RCV means received:

"status": "RCV"

Branch on the exact code string. Do not attempt to parse it as a readable label or to match on a prefix.

Reasons

reason_category groups the many ways a return can arise. The distinctions that matter operationally:

Group	Covers
Fault of the goods	Damaged, defective
Fault of the fulfilment	Wrong item sent, item missing from the shipment, not as described
Never arrived	Not delivered, not received, not received on time
Customer changed their mind	No longer needed, unwanted, not what was expected

These four groups behave differently and it is worth mapping them explicitly. A damaged-goods return is a supplier or carrier claim; a never-arrived return is a carrier investigation and may not involve returned goods at all; a changed-mind return is the only group where a restocking fee is normally defensible. Treating all twelve reason strings as one flat list loses that.

Example

A newly created return, showing how sparse the real payload is:

{
  "rma": "#1014-R5",
  "status": "RCV",
  "created_date": "2023-06-28T19:34:59.189838+00:00",
  "order_id": "524213310335630636",
  "customerEmail": "[e-mail]",
  "amount": null,
  "action_needed": null,
  "condition": null,
  "customer_id": null,
  "description": null,
  "enteredBy": null,
  "flat_rate_shipping": null,
  "order_date": null,
  "reason_category": null,
  "reported_condition": null,
  "requested_date": null,
  "serial_number": null,
  "shipped_date": null,
  "tax_refunded": null,
  "total_refunded": null,
  "tracking_number": null,
  "return_line_items": []
}

Related

• Get a return
• List returns
• Create a return
• Warranties — for claims against a product rather than a purchase