TBBNMerchantDocs
Available

Reputation

post/v1/reputation/reviews

Submit a 1-5 star review of a Merchant or a Space Branch — must be tied to a real completed trade session or Space booking the reviewer was actually a party to. 

curl -X POST https://api.tbbnetwork.com/v1/reputation/reviews \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "targetType": "MERCHANT",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "branchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "rating": 1,
  "comment": "comment",
  "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "spaceBookingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Request body

FieldTypeRequired
targetTypeMERCHANT | SPACE_BRANCHyes
merchantIdstring (uuid)—
branchIdstring (uuid)—
ratingintegeryes
commentstring—
tradeSessionIdstring (uuid)—
spaceBookingIdstring (uuid)—

Response (201)

FieldTypeRequired
idstring (uuid)—
reviewerIdstring (uuid)—
targetTypeMERCHANT | SPACE_BRANCH—
merchantIdstring,null (uuid)—
branchIdstring,null (uuid)—
ratinginteger—
commentstringnull—
tradeSessionIdstring,null (uuid)—
spaceBookingIdstring,null (uuid)—
createdAtstring (date-time)—
Example 201 response
{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "reviewerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "targetType": "MERCHANT",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "branchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "rating": 1,
  "comment": null,
  "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "spaceBookingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "createdAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}
get/v1/reputation/merchants/{id}/reviews

A Merchant's reviews plus aggregate rating

curl -X GET https://api.tbbnetwork.com/v1/reputation/merchants/{id}/reviews \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

idpathrequired

Response (200)

FieldTypeRequired
reviewsobject[]—
averageRatingnumbernull—
reviewCountinteger—
Example 200 response
{
  "reviews": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "rating": 1,
      "comment": null,
      "reviewerName": null,
      "createdAt": "2026-07-01T12:00:00Z"
    }
  ],
  "averageRating": null,
  "reviewCount": 1
}
get/v1/reputation/branches/{id}/reviews

A Space Branch's reviews plus aggregate rating

curl -X GET https://api.tbbnetwork.com/v1/reputation/branches/{id}/reviews \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

idpathrequired

Response (200)

FieldTypeRequired
reviewsobject[]—
averageRatingnumbernull—
reviewCountinteger—
Example 200 response
{
  "reviews": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "rating": 1,
      "comment": null,
      "reviewerName": null,
      "createdAt": "2026-07-01T12:00:00Z"
    }
  ],
  "averageRating": null,
  "reviewCount": 1
}
get/v1/reputation/businesses/{id}/reviews-summary

Aggregate rating across every Merchant and Branch linked to a Business. 

curl -X GET https://api.tbbnetwork.com/v1/reputation/businesses/{id}/reviews-summary \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

idpathrequired

Response (200)

FieldTypeRequired
averageRatingnumbernull—
reviewCountinteger—
Example 200 response
{
  "averageRating": null,
  "reviewCount": 1
}
get/v1/reputation/sellers/{id}

Get a seller's reputation score (0-100). A new seller starts at the neutral baseline of 50. 

curl -X GET https://api.tbbnetwork.com/v1/reputation/sellers/{id} \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

idpathrequired

Response (200)

FieldTypeRequired
sellerIdstring (uuid)—
scoreinteger—
Example 200 response
{
  "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "score": 1
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}