/v1/projects/{projectId}/suppliers/me.
The day view
Pick the window
GET /suppliers/me/bookings returns the bookings that start between
startDate and endDate. Both are UTC instants, and both ends are
included. A supplier thinks in local days, so turn their local midnight into
an instant first, and end the window one millisecond before the next local
midnight:
- Work the bounds out from local midnight on each date, not by adding 24
hours: a daylight-saving day is 23 or 25 hours long. Take the zone from the
supplier’s profile
timezone. - Always send milliseconds, as
.000Z. The bounds are compared with each booking’s start as text, so2026-11-03T05:00:00Zsorts after2026-11-03T05:00:00.000Z, and a booking that starts exactly at midnight is left out. - Never send
endDatebeforestartDate.
List the bookings
expand adds one key per value. Ask only for what the screen shows:
Every value except
client needs both dates, at most 93 days apart.
client alone works without a window. Each rule is a 400 BAD_REQUEST
whose message names the problem:
The list holds every status,
CANCELLED included. Send status to narrow it
to one status, or show cancelled rows struck through so the supplier sees what
changed.
A row, trimmed:
bookingTz, labelled. For the full detail, with
service lines and participants, call GET /suppliers/me/bookings/{bookingId}. Booking notes
and the client’s own report are never returned to a supplier.
Show only the actions the server allows
Every row carriesviewerActions, with or without expand. The server works
it out from the service’s settings, the booking’s status and its own clock.
Render from it; don’t re-derive the rules in your portal, or from the
supplier’s device clock.
blockedReason is ready to show. It takes one of these forms, with the
service’s own notice windows in hours:
Changes close 24 h before the session.Cancelling closes 24 h before the session.Rescheduling closes 24 h before the session.Cancelling closes 24 h and rescheduling 12 h before the session.
viewerActions is true when you read it. A notice window can close between
the read and the click, so the action can still be refused, with
409 NOTICE_WINDOW_PASSED. Re-read the booking and redraw. For the requests
and every refusal, see
Cancel and reschedule.
Keep the agenda current
The public API sends no webhooks. To catch a booking that is added, moved or cancelled, poll:GET /suppliers/me/alerts/summaryfor the badge, no more often than every 60 seconds. It carries counts only.GET /suppliers/me/alerts?filter=unreadwhen the count goes up. ALESSON_ASSIGNED,LESSON_MOVEDorLESSON_CANCELLEDalert names the booking intarget.bookingId. Re-read that booking.GET /suppliers/me/bookingsfor the window on screen, when the supplier opens or refreshes it.
After the booking ends
When a report can be filed
A supplier can report once the booking has ended, until it is settled. That means:SCHEDULEDorSTARTED, oncebookingEndUtchas passed;AWAITING_CONFIRMATION, at any time.
AWAITING_CONFIRMATION. An hourly sweep moves an ended booking
there, so it can still read SCHEDULED for up to an hour after it ends. A
report in that gap settles it straight away. myReport.reportable in the
list, and reportable below, already follow these rules. Use them to show the
report button.
Read the report view
reportablesays whether a report is taken now, by the server’s clock.ifAttendedandifNotAttendedsay what each answer would do. UsesettlesTofor the confirm step: “This marks the booking completed.” Each also carries aconsequenceskey, which names the MarketBox dashboard’s own copy. Don’t build on it. Both arenullwhen the booking isn’t reportable.reportis the supplier’s report on file, ornull.
ifAttended is judged from the booking alone. It never reads the client’s
report. So an ifAttended of COMPLETED can still end DISPUTED. Don’t
promise the supplier “completed” before they file.
File the report
attended says whether the supplier attended. It’s a self-report: it
says nothing about the client. note is optional, at most 1,000 characters,
and is kept with the report. The body takes no ids: the supplier is the one
the token belongs to.
The report settles the booking in the same write:
A supplier report never sets
CLIENT_NO_SHOW. To record that the client
didn’t come, the business sets CLIENT_NO_SHOW with the API key. See
The booking lifecycle.
The 201 returns the same report view, now with report filled in.
The response carries no booking status. The report view says what each
answer would do. It doesn’t say what the booking became. To show the
outcome, re-read the booking:
data.booking.status. No read tells the supplier what the client
reported. A booking that reads DISPUTED is enough: the business resolves it
in the MarketBox console.
Retrying is safe
Filing the sameattended again returns 200, with the report view, and
changes nothing. So when a POST times out, send it again. Your portal can’t
tell a lost request from a lost response, and it doesn’t need to.
- Only
attendedis compared. A retry with a differentnotestill returns200, and the firstnoteis kept. - A booking cancelled since the first
POSTanswers the retry with422 BOOKING_NOT_REPORTABLE, even when a report is on file.
When a report is refused
The two
409 bodies carry the code, message and statusCode, without a
requestId. A different answer on file also names it:
422 BOOKING_NOT_REPORTABLE uses the standard envelope, with one of two
messages:
"This booking was cancelled, so there is no attendance to report."
After it settles
COMPLETEDisn’t final straight away. A client who reports that they didn’t attend within 24 hours of the booking becomingCOMPLETEDmoves it toDISPUTED. The business can also move it back toAWAITING_CONFIRMATIONwithin its reversal window, 7 days by default, counted fromstatusUpdatedAt. Show “Completed”, but run anything final in your own records, such as a supplier’s pay, after those windows.- Nothing settles a booking on a timer. No job completes a booking that
nobody reported on. If the supplier never files, the booking stays
AWAITING_CONFIRMATIONuntil the business settles it. That’s why the next section matters.
Overdue reports
GET /suppliers/me/alerts/summary carries a MY_REPORTS_OVERDUE condition
while the supplier has bookings waiting for their report:
- Poll at most every 60 seconds. The count may lag by up to 5 minutes.
countis the supplier’s bookings inAWAITING_CONFIRMATION, capped at 100. The condition is left out when there are none, rather than sent with0.- It’s a condition, not an alert. It has no read state, and Mark all as read doesn’t clear it. It leaves when the supplier files the reports, up to 5 minutes later.
- It counts only bookings the hourly sweep has reached. A booking that ended
in the last hour can be reportable and not yet counted. The day view’s
myReport.reportableshows those.
target to a list of the bookings awaiting a report:
count, or send
status=AWAITING_CONFIRMATION with expand=client only, which needs no
window.
Reference
Endpoints used in this guide
Errors and edge cases
See Errors for the envelope, and
Bookings for every status.