`return` Return

An ordered item was returned, with the return's reason code.

When to send it

Our server, from the shop's returns (S08.06).

Needs no shopper consent.
Kept 25 months.
Send tracking_id when you have it: without one the event is kept but marked untracked.

Required fields

Field	Type	Rules
`client_id`	`integer`	greater than 0
`event`	`"return"`
`timestamp_ms`	`integer`
`product_id`	`string`	1–255 characters
`order_id`	`string`	1–255 characters
`order_date`	`string`	matches ^\d{4}-\d{2}-\d{2}(T[\d:.]+(Z\|[+-]\d{2}:?\d{2})?)?$
`return_date`	`string`	matches ^\d{4}-\d{2}-\d{2}(T[\d:.]+(Z\|[+-]\d{2}:?\d{2})?)?$
`return_reason`	`"COLOR" \| "DEFECTIVE" \| "NOT_AS_DESCRIBED" \| "OTHER" \| "SIZE_TOO_LARGE" \| "SIZE_TOO_SMALL" \| "STYLE" \| "UNKNOWN" \| "UNWANTED" \| "WRONG_ITEM"`
`size`	`string`	1–64 characters
`quantity`	`integer`	greater than 0

Optional fields

Field	Type	Rules
`tracking_id`	`string`	a UUID
`event_id`	`string`	1–255 characters
`schema_version`	`1`
`user_agent`	`string`	at most 2048 characters
`shop_country`	`string \| null`	at most 8 characters; may be null
`channel`	`string \| null`	at most 64 characters; may be null
`instance_id`	`string`	1–255 characters
`brand_id`	`integer \| null`	greater than 0; may be null
`product_associated`	`boolean`
`ab_data`	`object`
`testEvent`	`true`
`extra`	`object`
`price`	`number`	0 or more
`currency`	`string`	3 capital letters (ISO 4217)

Example

Test values only. This example passes the event's schema.

{
  "event": "return",
  "client_id": 1000,
  "timestamp_ms": 1792000000000,
  "product_id": "TEST-JACKET-01",
  "order_id": "TEST-ORDER-1001",
  "order_date": "2026-10-01",
  "return_date": "2026-10-12",
  "return_reason": "SIZE_TOO_SMALL",
  "size": "M",
  "quantity": 1,
  "price": 59.9,
  "currency": "EUR"
}

Checks and messages

What Tracking debug in your back office checks for this event, with its exact message. An error means the event is not counted; a warning means it is counted but something is likely wrong; an info is a hint.

Level	Check	Message
error	`body_data`	the field: body data is not allowed here, the value was dropped (D110)
error	`invalid_field`	what is wrong with the field
error	`over_limit`	the field is over the limit of <limit>
error	`product_id_missing`	missing product_id
warning	`currency_not_iso`	the field "<value>" is not an ISO 4217 currency code (3 letters, such as EUR)
warning	`price_text`	the field was sent as text: send a number (stored as <value>)
warning	`product_unknown`	product not found in your catalogue or has no size chart
warning	`size_not_in_product`	size "<value>" is not one of the product's sizes
warning	`timestamp_missing`	timestamp_ms is missing or not a time in milliseconds: the time the event was received is used
warning	`timestamp_out_of_range`	timestamp_ms is more than 30 days old or more than 3 days ahead: the time the event was received is used
warning	`untracked`	untracked: no tracking_id. The event is kept but cannot be joined to the widget visitor.
info	`size_lower_case`	size "<value>" was sent in lower case. Use uppercase letters or numbers.

JSON schema

The schema the API checks this event against: return.schema.json.

return Return