Skip to main content
GET
Fraud-blocked returns report

Authorizations

X-API-Key
string
header
required

Query Parameters

start
string<date>

First day to count, inclusive (YYYY-MM-DD). Defaults to 30 days before end. A span longer than 366 days is clamped to the most recent 366 days rather than refused, and the response sets period_truncated.

end
string<date>

Last day to count, inclusive (YYYY-MM-DD). Defaults to today in time_zone. If end precedes start the two are ordered — two dates delimit one interval, and which was typed first is not a fact about the data.

time_zone
string
default:UTC

IANA time zone the date range is resolved against, e.g. America/Chicago. A retailer's month ends at local midnight, not UTC midnight, and the difference lands real transactions in the wrong month.

Maximum string length: 64

Response

OK

Tenant-scoped fraud-blocked report for one period.

period_start
string<date-time>
required

First instant counted, in UTC. Inclusive.

period_end
string<date-time>
required

First instant not counted, in UTC. Exclusive — it is midnight at the start of the day after the requested end date, so the whole of end is inside the report.

time_zone
string
required

IANA time zone the requested date range was resolved against.

period_truncated
boolean
required

True when the requested span exceeded the maximum and the window above is the clamped one — the most recent allowed period. Every number in this response describes period_start..period_end, not the range that was asked for.

total_attempts
integer
required

Every verify call in the period, all decision states.

total_distinct_units
integer
required

Distinct units summed across states. A unit verified in two different states counts once in each, because those are two different events at the desk.

by_decision
DecisionBreakdownSchema · object[]
required

One entry per decision state, always all of them — a state with no activity reports zeroes.

declined_attempts
integer
required

Attempts that were declined return attempts (already_returned, never_sold, unknown_serial).

declined_distinct_units
integer
required

Distinct units behind declined_attempts.

declined_units_with_price
integer
required

Of declined_distinct_units, how many carried a recorded sale price.

estimated_prevented_value
CurrencyTotalSchema · object[]
required

Estimated value of the declined return attempts, per currency. An estimate, computed from the sale prices recorded on the units' own sale events — not a booked loss, and covering only declined_units_with_price of the declined units. recalled_lot is excluded: a recall block is product-safety handling, not a fraud attempt.