Skip to main content
This guide covers both halves of ratings:
  • 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.
Every call here uses the API key, so it runs on your server. There is no client-plane or supplier-plane route for reviews. Your server decides who may rate which booking, and the API doesn’t check it for you. For the fields and the attendance report, see Reviews and reports.

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.
The link proves nothing about who clicked. A link to your own review page carries bookingId, role and, on a star link, rating. It carries no token. Anyone can edit any of them. Sign the visitor in, then check they’re on the booking, before you show the form. Use rating only to pre-select the stars.

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 their clientId 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’t CANCELLED. 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 bookingEndUtc with now. MarketBox sends its own rating email an hour after the end. See Emails.
  • Don’t wait for a status. A booking stays AWAITING_CONFIRMATION until the supplier files an attendance report, which may be never.
  • Decide about no-shows and disputes. A CLIENT_NO_SHOW, SUPPLIER_NO_SHOW or DISPUTED booking 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.
Attendance is a separate call, and a review says nothing about who attended. A client report of “didn’t attend”, filed with your key before the supplier reports, turns the supplier’s later “attended” into 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 from GET /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
The body carries no ids. You can’t name the supplier or the client. MarketBox reads both off the booking, so a review can only ever be about the two parties who were on it.
  • direction is required.
  • ratingStars is a whole number from 1 to 5.
  • reviewText is optional, up to 5000 characters.
201 Created
Read 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
The 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 409 means the first one did.
The check is part of the write, so two simultaneous submits can’t both win. A review in the other direction is never blocked by this one.

The booking is cancelled

422 Unprocessable Entity
Don’t retry. This comes before the duplicate check, so a cancelled booking returns 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
For 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
MarketBox updates the average in the same write as each review, so you never compute it. 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:
The example is trimmed. recent holds the 5 newest reviews, each a full review object. It’s a preview, not the full set.
The supplier detail carries contact fields. It returns the supplier’s email, phone, street address and coordinates, and externalData. Each review in recent carries the client’s clientId and full name. Never pass the response to a browser. Copy only the fields your page renders.
Build the public profile on your server:
Showing reviewers by first name is a choice, not an API rule. Decide with the business what a public page shows. A review from the older 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 cursor for the next page. nextCursor: null is the only end of results. A cursor is valid only with the supplierId that produced it. See Pagination.
  • Rows carry ids only. This list has no supplierName or clientName. recent on the profile carries names for the 5 newest reviews. Past those, GET /bookings/{bookingId}/reviews returns names for one review’s booking.
  • Don’t average a page. Use averageRating from the summary. Averaging the first page gives a wrong number.
  • An unknown supplierId isn’t an error. It returns an empty page, so an empty list doesn’t confirm the id was right.
Leave out 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-summary returns the client’s averageRating and reviewCount, with the same zero rule as a supplier.
  • GET /clients/{clientId}/reviews lists the reviews suppliers wrote about the client, paginated. Unlike GET /reviews, its rows carry supplierName and clientName.
Both return 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 after COMPLETED.
  • Send direction, ratingStars and reviewText only. Ids come off the booking.
  • Treat 409 REVIEW_ALREADY_EXISTS as “already answered”.
  • Check reviewCount before you render stars.
  • Copy only the fields you render from the supplier detail.