Skip to main content
A supplier’s working year is rarely one weekly pattern. They take a holiday, block a lunch hour, work longer days in summer, and sometimes move. This guide shows how to model each of those on the supplier plane, as the signed-in supplier, and how to check what clients will be offered. It builds on two guides: Paths are relative to /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:
  1. Schedules. Each ACTIVE schedule that serves the offering at the requested place is expanded, day by day, in its own timezone.
  2. Minus exdates. A date in a schedule’s exdates removes that schedule’s hours on that date.
  3. Minus blocked time. Every ACTIVE blocked time is expanded the same way and subtracted, whatever schedule it overlaps.
  4. Minus bookings. Every booking of the supplier that isn’t CANCELLED occupies its time.
  5. Minus active holds. A hold occupies time exactly like a booking until it lapses or converts.
Busy events from a connected Google Calendar are subtracted too. Travel time and buffers around bookings are applied on top. When these steps leave a break in a day, each block of the day is treated on its own. Two ranges on one weekday, two schedules on one date, or blocked time in the middle of a range each make a break. Every block offers its own first and last time. With hours of 9:00–13:00 and 15:00–18:00, a 30-minute service can start at 12:30 and at 15:00. Ranges that touch, such as 9:00–13:00 and 13:00–17:00, are one block. See How offered times are worked out. 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:
A monthly pattern, such as “the first Saturday”, has no rule here. Model it as a weekly rule plus 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:
An exdate removes the hours that start on that date. For a range with 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:
The 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:
A range in 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.
Blocking time doesn’t touch bookings already in it. A blocked time, an exdate or a shorter schedule stops new bookings. A booking that already sits in that time stays booked, and the client still expects the supplier. Before you save time off, list the supplier’s bookings in that range with GET /suppliers/me/bookings?startDate=…&endDate=…, and move or cancel them. See Cancel and reschedule.
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 are ACTIVE 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":
The 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 PATCH:
Send the dates and 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.
Deleting a season you cloned from keeps the shared zone. A clone names the same travel zone as its original. Deleting a schedule whose 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:
This example adds a date to exdates. It builds the change from the row it just read, so a retry merges with whatever the other writer saved:
Don’t resend a stale form unchanged with a fresh version. That overwrites the other writer’s change, which is what version exists to prevent. A few things about the overlap check:
  • Only ACTIVE schedules are checked. Saving an INACTIVE row never conflicts. The check runs when it becomes ACTIVE.
  • 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.
Blocked time is never checked for overlap. It may overlap anything, which is the point.

When the supplier’s timezone moves

A schedule and a blocked time copy their timezone 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 INACTIVE rows 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 next PATCH it.
  • 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:
Bookings don’t move. A booking is a fixed instant with its own 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:
For a mobile supplier, send the client’s 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:
Read it against what you expect:
  • 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 its serviceOfferingIds.
  • The supplier isn’t in data at 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.
See Availability for the full request and response.

Reference

Endpoints used in this guide

Errors and edge cases

A VALIDATION_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.