​
Overview

After an escrow reaches a terminal state (released or refunded), either party can leave a review for the other. Reviews are mutual and anonymous to the reviewee until submitted — you cannot see the other party’s review before writing yours. Reviews feed directly into a user’s public profile stats:
  • avg_rating — running average of all received ratings (1–5 stars)
  • review_count — total number of reviews received
These stats are visible to all users on the public profile and factor into counterparty trust decisions.

​
Submitting a review

POST /review-submit
Authorization: Bearer <token>

{
  "escrow_id": "<id>",
  "rating": 5,
  "feedback": "Fast, honest, and easy to work with. Would trade again."
}
FieldConstraints
escrow_idMust be a terminal escrow the caller was a party to
ratingInteger 1–5
feedbackOptional, max 2000 characters
Reviews can only be submitted once per party per escrow. A second call on the same escrow returns a 409.

​
Listing reviews for a user

Returns all reviews received by a specific user, most recent first: 
GET /review-list?user_id=<uuid>&limit=20
Authorization: Bearer <token>
Supports cursor pagination via before: 
GET /review-list?user_id=<uuid>&limit=20&before=2026-04-01T00:00:00Z

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": "r1s2t3u4-v5w6-7890-abcd-ef1234567890",
      "escrow_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "escrow_title": "iPhone 15 Pro Max 256GB",
      "reviewer_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "reviewer_first_name": "Chidi",
      "reviewer_last_name": "Obi",
      "reviewer_avatar_url": "https://...",
      "reviewee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rating": 5,
      "feedback": "Fast, honest, and easy to work with.",
      "created_at": "2026-04-20T10:00:00Z"
    }
  ]
}

​
Rules

  • Only parties to the escrow can review each other — no third-party reviews
  • The escrow must be in a terminal state (released or refunded) before a review can be submitted
  • Reviews cannot be edited or deleted after submission
  • reviewer_id is included in the response so your UI can distinguish “reviews you wrote” from “reviews you received” when building a profile page