Skip to main content
A supplier profile page shows one supplier to clients: who they are, how they’re rated, what they offer and when they’re next free. This guide builds it on your server, from two reads:
  • GET /suppliers/{supplierId} for the profile, photo, rating, services and working pattern.
  • POST /availability/suppliers for the next time a client can book.
Both take the API key alone, so both run on your server. Your server returns only the fields the page renders.

Read the supplier

Read one supplier
The response is the whole supplier. This example is trimmed to the fields this guide uses:
For every field, see Reading one supplier.
The response carries the supplier’s contact details. It returns their email, phone, street address and coordinates, externalId and externalData. Each review in rating.recent carries the client’s clientId and full name. Never pass the response to a browser. Copy only the fields your page renders, on your server.

A supplier who can’t be shown

  • An unknown or deleted supplier is a 404. The same answer covers an id from another project:
    Render your own “not found” page.
  • An inactive supplier is returned, with active: false. The page still renders. Decide with the business whether to show a paused supplier, and don’t offer a time for one.
  • active: true doesn’t mean bookable. A supplier with availability.schedules: [] has no working hours. Only an availability search says when they’re free. See Show the next opening.

Show the photo

avatarUrl is one image: 256 × 256 pixels, WebP, cropped to fill the square. It’s null when the supplier has no photo, so render a placeholder.
  • The API exposes only this one URL. No field gives another size or format. Display it at up to 256 CSS pixels wide, or 128 on a high-density screen. Don’t build other sizes by editing the URL: its shape isn’t part of the API.
  • The URL changes when the photo changes. The old photo’s images are deleted when a new one is attached, so a stored old URL breaks. Cache avatarUrl no longer than you cache the rest of the profile.
  • Removing the photo sets avatarUrl to null.
To upload a photo, see Supplier portal: profile and photo or Provision your catalog and suppliers.

Show the rating

The detail carries rating: averageRating, reviewCount and the 5 newest reviews in recent.
  • Check reviewCount before you render stars. An unreviewed supplier has averageRating: 0 and reviewCount: 0. Render “No reviews yet”, not zero stars.
  • Strip the reviewers’ details. Show what the business agrees to, such as the stars, the text and a first name.
  • For the badge alone, GET /suppliers/{supplierId}/review-summary returns just supplierId, averageRating and reviewCount. Use it to refresh the rating without re-reading the whole profile.
See A supplier profile page for the rating block in full, and Every review of a supplier to page through the rest.

List the services

services[] lists what the supplier offers: each entry is a serviceId and a name.
  • Only LIVE services appear. A supplier mapped to a DRAFT or INACTIVE service doesn’t list it.
  • name is keyed by language, such as { "en": "Deep tissue massage", "fr": "Massage des tissus profonds" }. Pick the client’s language, and fall back to one the service has.
  • There are no prices or durations. Those live on the service’s offerings. Read them with GET /services/{serviceId}/offerings?status=ACTIVE. Amounts are integer minor units, so 4500 is $45.00, and the price can depend on where the session happens. See Offerings and Regional pricing.
The catalog changes rarely. Cache each service’s offerings on your server, and refresh them when the business edits the catalog.

The working pattern

availability.schedules[] is when and where the supplier works, such as “Mon, Wed, 9:00 AM – 5:00 PM” from each schedule’s summary. Show it as working hours, not as free times: it ignores bookings and time off. See Availability is a pattern, not a list of times.

Show the next opening

No availability route takes a supplierId for one supplier’s single sessions. POST /availability/suppliers returns every supplier who serves the service at the place you ask about, a page at a time.
Sending supplierId to POST /availability/suppliers doesn’t filter. The field isn’t in the request schema, so it’s dropped without an error. You get the first page of every matching supplier, which may not include the one you asked about. Find the supplier by data[].supplier.supplierId instead.
To find one supplier’s next opening, page through the results until their entry appears:
  • Choose the place. The search needs a locationId, or lat and lng. For a supplier who works at a venue, send the locationId of a PHYSICAL entry in their locations[]. For one who travels to clients, send the client’s address as lat and lng. Without a client address, show the working pattern instead of a time.
  • days: [] means nothing is free in the window. The supplier serves the offering there, but every slot is taken. Say “No times in the next two weeks”, or search again with a larger lookAheadDays.
  • Not in any page usually means not offered here. The supplier doesn’t serve that offering at that place, or isn’t searchable right now, such as a paused supplier.
  • Check errors on each page. A page can come back 200 with messages in errors, when part of the search couldn’t be computed. Treat a missing supplier on such a page as unknown, not as “not offered”.
  • The time can be taken before the client books. An open slot isn’t a hold. Re-check when the client picks it, or hold it. See Hold slots during checkout.
Each page computes availability for up to 50 suppliers, so this is the slowest part of the page. Run it after the profile renders, or cache the answer on your server for a few minutes. Every page is also logged as a search for supplier insights, and every supplier on it with at least one open slot counts as appearing. The x-mb-client-kind: server header tags these lookups as your server’s. See Report site events. For the request fields and the response in full, see Search suppliers by availability.
For a package, POST /availability/package-slate and POST /availability/package-options do take a supplierId, and plan the package’s sessions with that supplier only. See Create a package booking.

Put it together

Build the public profile on your server, and return only this to the browser:
Showing a last initial, and leaving reviewers unnamed, are choices for this example, not API rules. Agree with the business what a public page shows. When the page loads in a browser, send a profile_view event, so the supplier’s insights count the visit. See Report site events.

Reference

Endpoints used in this guide

Errors and edge cases

See Errors for the envelope and every code.