- Build a supplier portal covers sign-in and the two credentials on its Sign-in and access page, and the field rules for a schedule and a blocked time on its Availability page. Read Hours and blocked time first.
- Set up a mobile supplier’s service area covers travel zones. Everything below applies to a schedule that names a zone, too.
/v1/projects/{projectId}/suppliers/me. Every call takes
your API key and the supplier’s access token.
How availability is assembled
For each supplier, MarketBox works out open time on every request, from the rows you write here:- Schedules. Each
ACTIVEschedule that serves the offering at the requested place is expanded, day by day, in its owntimezone. - Minus
exdates. A date in a schedule’sexdatesremoves that schedule’s hours on that date. - Minus blocked time. Every
ACTIVEblocked time is expanded the same way and subtracted, whatever schedule it overlaps. - Minus bookings. Every booking of the supplier that isn’t
CANCELLEDoccupies its time. - Minus active holds. A hold occupies time exactly like a booking until it lapses or converts.
INACTIVE and deleted rows are
ignored. None of these steps is cached, so a change to hours or blocked time
shows in the next availability search.
How rrule works here
Every schedule and blocked time carries a weekly rule, such as
FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE. It isn’t a full RFC 5545 engine. The
rule must be FREQ=WEEKLY with no DTSTART, and only three parts are read:
Other parts are accepted and ignored.
COUNT isn’t read. An ordinal in
BYDAY is dropped: BYDAY=1SA saves without an error and is offered every
Saturday.
The row’s own fields carry the rest. startDate and endDate bound it, as
YYYY-MM-DD dates in its timezone. Each range in weeklyTimeRanges names
its own dayOfWeek and HH:MM times.
BYDAY filters the ranges. A range whose dayOfWeek isn’t in BYDAY is
never offered, and nothing warns you. Keep the two in step: when you add a
Friday range, add FR to BYDAY.
Times are wall-clock times. 09:00 is 09:00 in the row’s timezone on
every date, on either side of a daylight-saving change. A range with
crossesMidnight: true ends on the next day, and belongs to the day it starts.
Any other FREQ, or a rule with DTSTART, is refused before anything is
saved:
exdates for the Saturdays they don’t work, or as a
schedule per date range.
Exceptions: exdates or blocked time
Two tools take time out of a schedule. They do different jobs:
A rule of thumb: if the reason is the pattern (“we don’t run Tuesday
lessons on Christmas Eve”), use
exdates. If the reason is the supplier
(“I’m away”), use blocked time. A supplier with three schedules blocks a
vacation once, not three times.
Skip a date with exdates
exdates is replaced whole on PATCH. Read the schedule, add the date to the
list you got back, and send the full list with the row’s version:
crossesMidnight: true, the whole shift goes, including the part after
midnight. An overnight shift that starts the evening before the exdate still
runs into it.
Block time off
A week of vacation, every day blocked in full:201 returns the row in data, with its blockedTimeId (a blk_ id)
and version: 1. allDay: true blocks from local midnight to the next local
midnight, so a daylight-saving day is blocked in full.
Part of one afternoon:
timeRanges with no dayOfWeek applies on every day the rule
allows. Give it a dayOfWeek to block, say, Monday mornings only.
Each shape refuses the other’s fields. allDay: true with ranges is a 400:
allDay: false with no ranges is timeRanges must contain at least one range when allDay is false.
To end a block early, PATCH its endDate. To remove it, DELETE it (204).
A stale version on a blocked time is 409 VERSION_CONFLICT with
"Blocked time was modified by another writer".
Seasons
A season is a schedule with a date range. A supplier who works longer days in summer has two schedules: one for the school year and one for summer, with dates that don’t overlap. Both areACTIVE all year. Each offers hours only
between its own startDate and endDate.
1
End the current season on its last day
PATCH the current schedule’s endDate to the day before the new season
starts, for example "endDate": "2027-06-27", with its version. Leave it
ACTIVE: after its endDate it offers nothing. Do this first. While the two
date ranges overlap, the new season can’t be switched on.2
Clone it
POST /schedules/{scheduleId}/clone takes no body. It copies the schedule’s
hours, offerings, venues, zone, and any start and end of day locations into
a new row, with a new sch_ id and
status: "INACTIVE":201 returns the clone, at version: 1. An INACTIVE schedule offers
nothing, so the supplier can edit it without clients seeing half-made hours.3
Edit the clone and activate it
Change its dates and hours, and switch it on, in one Send the dates and
PATCH:status together. A clone has the same dates and hours
as the schedule it came from. Activating it before you change them overlaps
the original, and is refused with 409 CONFLICT.travelZoneRef names one of the supplier’s own zones soft-deletes that zone
only when no other schedule of the supplier still uses it. A paused
(INACTIVE) schedule counts. So the other season keeps its zone. To retire a
season without deleting it, let its endDate pass, or set its status to
INACTIVE. See
Remove a zone, or stop working in it.
When a save is refused with 409
Schedule writes have two 409s with different fixes. Branch on code, not
the status:
The overlap answer names the schedule it collides with:
exdates. It builds the change from the row it
just read, so a retry merges with whatever the other writer saved:
version. That overwrites
the other writer’s change, which is what version exists to prevent.
A few things about the overlap check:
- Only
ACTIVEschedules are checked. Saving anINACTIVErow never conflicts. The check runs when it becomesACTIVE. - Only real hours collide. Two seasons that meet, one ending on 2027-06-27 and the next starting on 2027-06-28, don’t. A range that ends at 12:00 and one that starts at 12:00 don’t either.
- It looks from today to a year ahead. Hours in the past never conflict. An overlap more than 365 days out isn’t caught when you save. Create a season less than a year before it starts, or check the dates yourself.
When the supplier’s timezone moves
A schedule and a blocked time copy theirtimezone once, when they are
created: the timezone you send, else the supplier’s profile zone, else the
project’s default. After that, the row keeps its zone. So when a supplier
changes timezone on their profile with PATCH /suppliers/me, their existing
hours don’t move. Rows created later take the new zone, and the supplier ends
up with hours in two zones.
To bring every row into the profile zone, call:
- It keeps wall-clock times. 09:00–17:00 in Toronto becomes 09:00–17:00 in Vancouver.
- It moves
INACTIVErows too, so a season you switch on later is already in the right zone. Deleted rows stay as they were. - The counts are the rows it rewrote. A row already in the zone isn’t counted.
- Each rewritten row gets a new
version. Re-read a schedule before you nextPATCHit. - A row someone edits at the same moment is skipped, and not counted. Call it again: it’s safe to repeat, and moves only what’s left.
- It doesn’t re-run the overlap check.
- You can’t choose the zone. When the profile has none, it uses the project’s default. When neither has one, it changes nothing:
bookingTz. A booking at 10:00 Toronto time stays at that instant, which is
07:00 in Vancouver, and may now sit outside the supplier’s hours. After a move,
list the supplier’s upcoming bookings and reschedule any that no longer fit.
A season somewhere else doesn’t need a profile change. Send timezone on
that season’s schedule, for example "America/Vancouver" for a winter spent
on the west coast, and leave the profile as it is. Each row expands in its own
zone.
Check the result
Open times are what clients are offered, so check them, not just the rows.POST /v1/projects/{projectId}/availability/suppliers takes the API key
alone, so your server can run it after the supplier saves:
lat and lng instead of
locationId.
Each entry in data holds a supplier and their open days. Find the
supplier by supplier.supplierId, following nextCursor if they’re not on
the first page. Trimmed:
- No 2026-12-21 to 2026-12-27 in
days. The vacation blocked time worked. A supplier with no open time on a date has no entry for it. days: []. The supplier matches the service and place, but has no open time in the window. Check the schedule’s dates,BYDAY,status, and that the offering is in itsserviceOfferingIds.- The supplier isn’t in
dataat all. The supplier doesn’t serve this offering at this place, or search hasn’t caught up with a schedule saved a moment ago. Which suppliers are returned comes from a search index that MarketBox updates shortly after a schedule is saved. Their open times are worked out live. Allow a short delay before you decide a new schedule failed.
Reference
Endpoints used in this guide
Errors and edge cases
AVALIDATION_ERROR message starts with the field’s path, such as
weeklyTimeRanges.0.crossesMidnight: . The messages below are what follows
it.
See Errors for the envelope,
Concurrency for
version, and Timezones for zones.