// guide

Reputation

Reputation is built from events, never from a number someone typed. We give you the counts as well as a score, so you can show your users what the score is made of.

Reputation events

Reputation events
event	written when	against	effect
`order_completed`	an order completes (9, 10, or 12)	both parties	good
`backed_out`	a party backs out (6)	who backed out	bad
`dispute_lost`	a dispute is decided (12, 13, or after completion)	who it went against	bad
`dispute_won`	the same decision	the other party	none, kept for the history
`lapsed`	the commitment window passes (8)	both parties	none, kept for the history
`review_received`	a review becomes visible	the party reviewed	feeds the rating

The numbers are the order transitions in the orders guide. Payment expiring (4) and cancelling by agreement (7) write no event.
Events never change and are never deleted. Your team can void one with a written reason, POST /v1/reputation_events/{id}/void; a voided event stops counting.
A buyer and a seller each have their own reputation, even with the same external_id. Reputation never crosses between marketplaces, or between test and live.

What a buyer or seller shows

Reputation fields
field	means
`completed_orders`	order_completed events in the window
`backed_out`	backed_out events in the window
`disputes_lost`	dispute_lost events in the window
`review_count`	visible reviews in the window
`average_rating`	the plain mean of those ratings, or null
`score`	0 to 100, or null until there are enough events
`level`	new, low, fair, good, or excellent

Levels: excellent at 90 and above, good from 75, fair from 50, low below 50, and new while the score is null.

The default score

Only events inside the rolling window count. If completed orders, back-outs, and lost disputes add up to fewer than the minimum, the score is null.

formula

C = completed_orders    B = backed_out    D = disputes_lost
n = review_count        S = sum of ratings

reliability = (C + 1) / (C + wB * B + wD * D + 1)
smoothed    = (S + prior_rating * prior_weight) / (n + prior_weight)
rating      = (smoothed - 1) / 4
score       = round(100 * (blend * reliability + (1 - blend) * rating))

A seller with 10 completed orders, 1 back-out, no lost disputes, and 6 reviews totalling 27, with the defaults:

worked example

reliability = (10 + 1) / (10 + 2*1 + 3*0 + 1) = 11 / 13 = 0.846
smoothed    = (27 + 4.0*2) / (6 + 2)          = 35 / 8  = 4.375
rating      = (4.375 - 1) / 4                           = 0.844
score       = round(100 * (0.6*0.846 + 0.4*0.844))      = 85, good

Settings

Change them under marketplace. Every score in the marketplace is worked out again from its events at once.

Reputation settings
setting	default	limits
rolling window	24 months	6 to 60 months
wB, weight of a back-out	2	1 to 5
wD, weight of a lost dispute	3	1 to 5
blend, the share given to reliability	0.6	0 to 1
prior rating	4.0	3.0 to 5.0
prior weight	2	0 to 10
minimum events for a score	3	1 to 10

next: payments and payouts