- Collect a review of one booking, from the client or from the supplier.
- Show a rating: a star badge, a supplier profile, and the full list of a supplier’s reviews.
Choose the direction
A review is one side of a booking rating the other.direction says which
side:
The two directions are independent. One booking can hold one review in each.
A review moves only the rated party’s average.
If your page is the target of MarketBox’s rating emails, the link tells you
which side clicked.
role=client means post CLIENT_TO_SUPPLIER.
role=supplier means post SUPPLIER_TO_CLIENT. See
What MarketBox puts in the link.
Check the reviewer is on the booking
The review route takes the booking from the path and both parties from the booking. It can’t tell who is calling, because your API key acts for the business. So check ownership yourself, before you post. For a client, resolve theirclientId from their token with
POST /clients/me. Read the booking, and refuse when its clientId differs.
Only the booking’s own client can review it. Another participant on a group
booking can’t, because the review is always attributed to the booking’s
clientId. Refuse a booking that hasn’t ended yet, too (see
Decide when to offer the form):
signedInClientId is the helper from
Create a single booking. It calls
POST /clients/me with the client’s token and returns data.clientId. See
Clients.
For a supplier, ask the supplier plane. Call
GET /suppliers/me/bookings/{bookingId} with the API key and the supplier’s
access token. It returns the booking only to its current supplier. Any other
booking is a 404, so a 200 is your ownership check. Check its
bookingEndUtc the same way. Then post SUPPLIER_TO_CLIENT with the API key.
See
Credentials and the token.
Decide when to offer the form
The API accepts a review of any booking that isn’tCANCELLED. The booking
doesn’t have to be COMPLETED. Nothing in MarketBox moves a booking to
COMPLETED automatically, so most ended bookings never reach it.
That means the API also accepts a review of a booking that hasn’t happened
yet. Gate the form yourself:
- Offer it once the booking has ended. Compare
bookingEndUtcwith now. MarketBox sends its own rating email an hour after the end. See Emails. - Don’t wait for a status. A booking stays
AWAITING_CONFIRMATIONuntil the supplier files an attendance report, which may be never. - Decide about no-shows and disputes. A
CLIENT_NO_SHOW,SUPPLIER_NO_SHOWorDISPUTEDbooking is still reviewable. MarketBox sends no rating emails for a no-show booking. Whether your page offers the form for one is your business’s call.
DISPUTED. A report filed
with your key doesn’t dispute a booking that is already COMPLETED. See
Attendance and disputes.
Show names before the first review
A form reads better with a name: “How was your booking with Jane?”. Get both names fromGET /bookings/{bookingId}/aggregate. Its parties object carries
parties.client.fullName and parties.supplier.fullName. It’s the only
public way to turn a clientId into a name. parties.supplier is null when
no supplier is assigned. Each fullName is best-effort and absent when the
profile can’t be resolved, so fall back to a neutral label.
Post the review
Leave a review
directionis required.ratingStarsis a whole number from 1 to 5.reviewTextis optional, up to 5000 characters.
201 Created
subjectType and subjectId to know who the review is about. Don’t
work it out from direction yourself. supplierName and clientName are
best-effort, and absent when a profile can’t be resolved. No email address is
returned for either party.
In the same write, MarketBox adds the rating to the rated party’s average. It
also stops that side’s rating follow-up emails for this booking. The other
side keeps getting its follow-ups, 3, 6 and 9 days after the end. See
Stopping the rating follow-ups.
A review is permanent. There is no update or delete route, and the average
it moved stays moved. Show the stars and text back to the reviewer before you
post.
When the post fails
The side has already reviewed the booking
A second review in the same direction is refused. Nothing is written, and the average doesn’t move:409 Conflict
message varies. It can also read already has a CLIENT_TO_SUPPLIER review or already has a SUPPLIER_TO_CLIENT review. Branch on code, never
on message.
Treat this 409 as “already answered”, not as an error:
- Show what’s on file. Read
GET /bookings/{bookingId}/reviews, and render that side’s review. - Retry safely. If a post timed out and you don’t know whether it
landed, send it again. A
409means the first one did.
The booking is cancelled
422 Unprocessable Entity
422 even when it already has a review.
The booking has no supplier
A booking with no supplier assigned has nobody to rate, in either direction:422 Unprocessable Entity
SUPPLIER_TO_CLIENT, the message ends so there is no supplier to review from instead. Once the business assigns a supplier, the same post
succeeds.
Other failures
Show existing reviews
GET /bookings/{bookingId}/reviews returns every review on the booking, in
both directions, newest first. It isn’t paginated. Use it so a returning
reviewer sees their own review rather than an empty form.
Don’t assume at most two. The older POST /reviews route doesn’t check
for duplicates, so a booking can hold several CLIENT_TO_SUPPLIER reviews.
Filter the list by direction; don’t index into it.
A review you just posted can take a moment to appear in this list, and in
every other review list. Render the
201 body for the reviewer, rather than
re-reading straight away.Show supplier ratings
Every one of these counts reviews of the supplier only. A review the
supplier wrote about a client never appears in them.
A star badge
Supplier rating summary
200 OK
averageRating is rounded to one decimal place.
Check reviewCount before you render stars. A supplier nobody has
reviewed returns averageRating: 0 and reviewCount: 0, not a 404. Render
“No reviews yet”, not zero stars. A 404 NOT_FOUND, Supplier not found,
means the id is unknown in this project, or the supplier was deleted.
GET /suppliers carries no rating. For a directory with a badge on each row,
call the summary for each supplier on your server, and cache it. The average
changes only when a review is written.
A supplier profile page
For the whole page, with the photo, services and next opening, see Build a supplier profile page.GET /suppliers/{supplierId} returns the whole supplier, with a rating
block:
recent holds the 5 newest reviews, each a full
review object. It’s a preview, not the full set.
Build the public profile on your server:
POST /reviews
route has no clientId, so it has no clientName either.
The detail returns an inactive supplier, with active: false, so a paused
supplier’s profile still renders. See
Rating and reviews.
Every review of a supplier
GET /reviews?supplierId={supplierId} pages through every review of the
supplier, newest first:
List a supplier's reviews
- Pass
cursorfor the next page.nextCursor: nullis the only end of results. A cursor is valid only with thesupplierIdthat produced it. See Pagination. - Rows carry ids only. This list has no
supplierNameorclientName.recenton the profile carries names for the 5 newest reviews. Past those,GET /bookings/{bookingId}/reviewsreturns names for one review’s booking. - Don’t average a page. Use
averageRatingfrom the summary. Averaging the first page gives a wrong number. - An unknown
supplierIdisn’t an error. It returns an empty page, so an empty list doesn’t confirm the id was right.
supplierId to list every review of every supplier in the project.
Show client ratings
Suppliers rate clients too. Two routes read those reviews. See Clients for the rest of the client record.GET /clients/{clientId}/review-summaryreturns the client’saverageRatingandreviewCount, with the same zero rule as a supplier.GET /clients/{clientId}/reviewslists the reviews suppliers wrote about the client, paginated. UnlikeGET /reviews, its rows carrysupplierNameandclientName.
404 NOT_FOUND, Client not found, for a client unknown in this
project, or deleted. Who may see a client’s rating is your business’s decision. These
routes don’t check who is asking.
Avoid the older project-level route
POST /reviews is the older, project-level route. It stays for existing
integrations. Use POST /bookings/{bookingId}/reviews for anything new.
Every review from the older route still counts toward the supplier’s average.
A review sent there without a
bookingId doesn’t stop the rating follow-up
emails, so the client keeps being asked.
To move over, put the booking in the path. Send direction: "CLIENT_TO_SUPPLIER", ratingStars and reviewText. Drop supplierId,
reviewerId and bookingId from the body. If the older route already holds a
review for that booking, the new one usually returns 409 REVIEW_ALREADY_EXISTS.
Reference
Endpoints used in this guide
Every route takes the API key. Each path follows the project prefix, as in/v1/projects/{projectId}/reviews.
Errors
- Call MarketBox from your server. The API key never reaches a browser.
- Sign the reviewer in, and check they’re on the booking, before you post.
- Offer the form after
bookingEndUtc, not afterCOMPLETED. - Send
direction,ratingStarsandreviewTextonly. Ids come off the booking. - Treat
409 REVIEW_ALREADY_EXISTSas “already answered”. - Check
reviewCountbefore you render stars. - Copy only the fields you render from the supplier detail.