> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a supplier portal

> Let suppliers manage their profile, bookings, hours, travel zones and insights from your own branded portal, through the supplier plane.

The **supplier plane** lets a supplier who signs in to your portal do what they
do in the MarketBox dashboard:

* keep their profile and photo up to date;
* see their bookings and file attendance reports;
* cancel or move a booking, when the service allows it;
* set their working hours, blocked time, travel zones and venues;
* read their demand and search insights;
* see and clear their alerts: new, moved and cancelled bookings.

Every route lives under one base path, and none of them names a supplier:

```
/v1/projects/{projectId}/suppliers/me
```

`me` is the supplier the user token belongs to. The API never reads a supplier
id from the path or the body. A booking, schedule, blocked time or travel zone
id that isn't theirs is a `404` — the same answer as an id that doesn't exist.

> [!NOTE]
>
> **The dashboard and your portal run the same code.** Every supplier-plane route
> is the twin of a dashboard route, with the same rules. A supplier gets the same
> answer, and the same refusal, from both.

A supplier portal signs in exactly as a booking flow does. For what is
specific to suppliers, start with
[Sign-in and access](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md).

## The pages of this guide

| Page | What it covers |
| - | - |
| [Sign-in and access](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md) | What you need first, the two credentials, checking access on sign-in, every refusal, removed versus never-invited suppliers, and the links in MarketBox emails. |
| [Profile and photo](https://docs.gomarketbox.com/guides/supplier-portal-profile-and-photo.md) | Reading and editing the profile, picking services and skills, and changing the photo. |
| [Bookings](https://docs.gomarketbox.com/guides/supplier-portal-bookings.md) | The day's agenda, attendance reports, rating the client, and cancelling or moving a booking. |
| [Availability](https://docs.gomarketbox.com/guides/supplier-portal-availability.md) | Working hours, blocked time, `exdates`, start and end of day locations, travel zones and venues: the field rules for each. |
| [Insights and alerts](https://docs.gomarketbox.com/guides/supplier-portal-insights-and-alerts.md) | Demand and search insights, and the alerts bell. |

Three task guides go deeper on the same plane:

* [Supplier day view and attendance reports](https://docs.gomarketbox.com/guides/supplier-day-view-and-reporting.md):
  the agenda's window and `expand` rules, `viewerActions`, every report
  outcome, and overdue reports.
* [Weekly hours, exceptions and seasons](https://docs.gomarketbox.com/guides/weekly-hours-exceptions-and-seasons.md):
  how `rrule` is read, holidays and time off, seasonal schedules, a timezone
  move, and checking the result.
* [Set up a mobile supplier's service area](https://docs.gomarketbox.com/guides/set-up-a-mobile-supplier-service-area.md):
  a travel zone and the hours in it, in order, and how to check a client's
  address is covered.

## First sign-in: set the supplier up

A supplier who signs in for the first time may have no hours yet. Set them up
in this order. The `/suppliers/me` calls take the API key and the supplier's
access token. The service list and the availability check take the API key
alone.

**1. Check access**

`GET /suppliers/me/access` answers `200` with `allowed` and a `reasonCode`.
Go on only when `allowed` is `true`; otherwise show its `message`. See
[Check access first](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#check-access-first).

**2. Read the profile**

`GET /suppliers/me` returns the supplier's own profile, including `timezone`
and `serviceIds`. See
[Edit the profile](https://docs.gomarketbox.com/guides/supplier-portal-profile-and-photo.md#edit-the-profile).

**3. Set the timezone**

`PATCH /suppliers/me` with `timezone`. Hours and blocked time take the
profile zone when you omit `timezone` on create. When neither the profile nor
the project has a zone, the create is a `400 BAD_REQUEST`. See [Times](#times).

**4. Set the services**

`PATCH /suppliers/me` with `serviceIds`, taken from
`GET /v1/projects/{projectId}/services?status=LIVE`. A schedule's
`serviceOfferingIds` must be `ACTIVE` offerings of these services. You can
send `timezone` and `serviceIds` in one `PATCH`.

**5. Choose where they work**

For in-home work, create the supplier's own travel zone with
`POST /suppliers/me/travel-zones`. See
[Set up a mobile supplier's service area](https://docs.gomarketbox.com/guides/set-up-a-mobile-supplier-service-area.md).
For a venue, pick one from `GET /suppliers/me/locations`. See
[Venues](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#venues).

**6. Create the schedule**

`POST /suppliers/me/schedules` with the hours, naming the zone in
`travelZoneRef` or the venue in `locationRefs`. **A travel zone on its own
makes no one bookable.** See
[Set working hours](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#set-working-hours).
If the project uses start and end of day locations, the schedule can also
carry where the supplier's day starts and ends. See
[Start and end of day locations](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#start-and-end-of-day-locations).

**7. Check what clients are offered**

`POST /v1/projects/{projectId}/availability/suppliers` takes the API key
alone, so your server can run it after the supplier saves. Find the supplier
by `supplier.supplierId` and read their open `days`. Search updates shortly
after a schedule is saved, so allow a short delay. See
[Check the result](https://docs.gomarketbox.com/guides/weekly-hours-exceptions-and-seasons.md#check-the-result).

## Times

* **A booking's time is an instant plus a zone.** `bookingStartUtc` and
  `bookingEndUtc` are UTC instants. `bookingTz` is the booking's home zone, and
  `bookingLocalDate`, `bookingLocalStartTime` and `bookingLocalEndTime` are the
  same times in that zone. Show the booking in its home zone, labelled.
* **A reschedule carries one UTC instant,** the new `startTime`. The booking
  keeps its length, and its local times are worked out again in its own zone.
* **Hours and blocked time are wall-clock rules:** `HH:MM` times and
  `YYYY-MM-DD` dates in the row's `timezone`, with a weekly `rrule`. Omit
  `timezone` on create to use the supplier's profile zone, or the project's
  default zone when the profile has none. When neither exists, the create is a
  `400 BAD_REQUEST`. An update keeps the row's stored zone.
* **Insights** are given in the supplier's home zone.
* **Query windows** on bookings (`startDate`, `endDate`) are UTC instants.

See [Timezones](https://docs.gomarketbox.com/concepts/timezones.md).

## Not on the supplier plane yet

These dashboard features have no supplier-plane route yet. Suppliers use the
dashboard for them:

* **Google Calendar** — connecting a supplier's calendar.
* **Invitations** — inviting a supplier into the project. A supplier accepts
  once in the dashboard, then signs in to your portal with the same account.

For everything else the API can't do yet, see
[What the API doesn't do](https://docs.gomarketbox.com/concepts/what-the-api-doesnt-do.md).

## Reference

### Endpoints used in this guide

Every route on the supplier plane takes the API key and the supplier's access
token.

| Endpoint | Methods |
| - | - |
| `/v1/projects/{projectId}/suppliers/me/access` | `GET` |
| `/v1/projects/{projectId}/suppliers/me` | `GET`, `PATCH` |
| `/v1/projects/{projectId}/suppliers/me/avatar/upload-url` | `POST` |
| `/v1/projects/{projectId}/suppliers/me/avatar` | `PUT`, `DELETE` |
| `/v1/projects/{projectId}/suppliers/me/bookings` | `GET` |
| `/v1/projects/{projectId}/suppliers/me/bookings/{bookingId}` | `GET`, `PATCH` |
| `/v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/cancel` | `POST` |
| `/v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/reports` | `GET`, `POST` |
| `/v1/projects/{projectId}/suppliers/me/schedules` | `GET`, `POST` |
| `/v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}` | `GET`, `PATCH`, `DELETE` |
| `/v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}/clone` | `POST` |
| `/v1/projects/{projectId}/suppliers/me/blocked-times` | `GET`, `POST` |
| `/v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}` | `GET`, `PATCH`, `DELETE` |
| `/v1/projects/{projectId}/suppliers/me/availability-timezone/apply-profile` | `POST` |
| `/v1/projects/{projectId}/suppliers/me/travel-zones` | `GET`, `POST` |
| `/v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}` | `GET`, `PATCH`, `DELETE` |
| `/v1/projects/{projectId}/suppliers/me/locations` | `GET` |
| `/v1/projects/{projectId}/suppliers/me/demand` | `GET` |
| `/v1/projects/{projectId}/suppliers/me/demand/suggestions/{key}/dismiss` | `POST`, `DELETE` |
| `/v1/projects/{projectId}/suppliers/me/search-insights` | `GET` |
| `/v1/projects/{projectId}/suppliers/me/alerts` | `GET` |
| `/v1/projects/{projectId}/suppliers/me/alerts/summary` | `GET` |
| `/v1/projects/{projectId}/suppliers/me/alerts/read-all` | `POST` |
| `/v1/projects/{projectId}/suppliers/me/alerts/{alertId}/read` | `POST` |

Key-only routes the portal also uses, with the API key alone:

| Endpoint | Methods |
| - | - |
| `/v1/projects/{projectId}/suppliers/{supplierId}` | `GET` |
| `/v1/projects/{projectId}/services` | `GET` |
| `/v1/projects/{projectId}/skills` | `GET` |
| `/v1/projects/{projectId}/locations` | `GET` |
| `/v1/projects/{projectId}/locations/{locationId}` | `GET` |
| `/v1/projects/{projectId}/availability/suppliers` | `POST` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.