Skip to main content
A supplier’s day in your portal has two halves. Before a booking, they need an agenda: who, what, where, and whether they can still move or cancel it. After a booking ends, they file an attendance report, and that report settles it. This guide builds both on the supplier plane. It builds on Build a supplier portal and its Sign-in and access page, which covers sign-in, the two credentials, and the refusals every supplier-plane route shares. Paths are relative to /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, so 2026-11-03T05:00:00Z sorts after 2026-11-03T05:00:00.000Z, and a booking that starts exactly at midnight is left out.
  • Never send endDate before startDate.
A booking that started the evening before and runs past midnight isn’t in that day’s list. Start the window a few hours earlier if the supplier works overnight.

List the bookings

The list isn’t paginated: every booking in the window comes back in one response. Keep the window to a day or a week. 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:
Show each booking in its own 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 carries viewerActions, 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.
It appears only when a notice window has closed. 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/summary for the badge, no more often than every 60 seconds. It carries counts only.
  • GET /suppliers/me/alerts?filter=unread when the count goes up. A LESSON_ASSIGNED, LESSON_MOVED or LESSON_CANCELLED alert names the booking in target.bookingId. Re-read that booking.
  • GET /suppliers/me/bookings for the window on screen, when the supplier opens or refreshes it.
See Alerts and Tracking state without webhooks.

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:
  • SCHEDULED or STARTED, once bookingEndUtc has passed;
  • AWAITING_CONFIRMATION, at any time.
Don’t wait for 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

Trimmed:
  • reportable says whether a report is taken now, by the server’s clock.
  • ifAttended and ifNotAttended say what each answer would do. Use settlesTo for the confirm step: “This marks the booking completed.” Each also carries a consequences key, which names the MarketBox dashboard’s own copy. Don’t build on it. Both are null when the booking isn’t reportable.
  • report is the supplier’s report on file, or null.
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:
and show 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 same attended 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 attended is compared. A retry with a different note still returns 200, and the first note is kept.
  • A booking cancelled since the first POST answers the retry with 422 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:
A cancelled booking reads "This booking was cancelled, so there is no attendance to report."

After it settles

  • COMPLETED isn’t final straight away. A client who reports that they didn’t attend within 24 hours of the booking becoming COMPLETED moves it to DISPUTED. The business can also move it back to AWAITING_CONFIRMATION within its reversal window, 7 days by default, counted from statusUpdatedAt. 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_CONFIRMATION until the business settles it. That’s why the next section matters.
See Attendance and disputes for every combination of reports.

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.
  • count is the supplier’s bookings in AWAITING_CONFIRMATION, capped at 100. The condition is left out when there are none, rather than sent with 0.
  • 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.reportable shows those.
Map target to a list of the bookings awaiting a report:
The window must be at most 93 days with these expansions. A supplier who hasn’t reported for longer than that has older bookings too: page back a window at a time until the total matches 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.