/v1/projects/{projectId}/suppliers/me. Every call
takes your API key and the supplier’s access token. See
Sign-in and access.
Hours and blocked time
Lists return
ACTIVE rows. Add includeInactive=true or includeDeleted=true
for the others.
This section has the field rules. For how rrule is read, holidays and time
off, seasonal schedules, a timezone move and checking the result, see
Weekly hours, exceptions and seasons.
Set working hours
-
GET /suppliers/me/locationsfor the venue picker. For the area picker,GET /suppliers/me/travel-zoneslists the supplier’s own travel zones, and the key-onlyGET /v1/projects/{projectId}/locations?locationType=TRAVEL_ZONElists the project’s.GET /suppliers/me/locationsnever returnsTRAVEL_ZONElocations, so a portal needs that key-only call too. -
Create the schedule. This one is for a venue:
Name each venue with both its
locationIdand itslocationTypefromGET /suppliers/me/locations. For an area, sendtravelZoneRefinstead of, or as well as,locationRefs. This schedule covers one of the supplier’s own zones, for one offering only:travelZoneRefnames one zone, in one of two shapes:A travel zone on its own makes no one bookable. The supplier is offered in an area only once anACTIVEschedule references its zone. Use the supplier’s own zone for in-home work. Search offers a supplier in a project zone, but a booking at a client’s address needs the supplier’s ownstz_id. Aloc_project zone in itslocationIdis a404 NOT_FOUND. See The supplier’s own zone or a project zone. -
To change it,
PATCH /schedules/{scheduleId}with the changed fields and the row’s currentversion.
400:
rruleisFREQ=WEEKLY, with noDTSTART.INTERVAL,BYDAYandUNTILare read. With noBYDAY, every day is allowed, so each range applies on its owndayOfWeek. To skip single dates, such as a public holiday, list them inexdatesasYYYY-MM-DD.- In each range,
startTimeandendTimediffer, andcrossesMidnightistrueexactly whenstartTimeis later thanendTime: a range that ends the next day. appliesToAllOfferings: truetakes noserviceOfferingIds.appliesToAllOfferings: falseneeds at least one.- Each of
serviceOfferingIdsis anACTIVEoffering of one of the supplier’s own services, the ones in their profileserviceIds. Anything else is400 BAD_REQUESTnaming the ids, such as “Offerings not active for this supplier: off_01kv60qge5eh59ap0gw0pqrrys”. - A schedule has at least one entry in
locationRefs, atravelZoneRef, or both. - Each venue and zone exists in the project, with the type you named.
422 refusals of their own. See
Start and end of day locations.
Two 409 cases to handle. Branch on code, because the status is the same:
CONFLICT: anACTIVEschedule may not overlap anotherACTIVEone. Change the dates or hours.VERSION_CONFLICT: the row changed since you read it, such as “Schedule was modified by another writer”. Re-read the row and try again. ADELETEcan also get it, when another write lands on the row at the same moment.
version the same way, with
409 VERSION_CONFLICT.
Deleting a schedule whose travelZoneRef names one of the supplier’s own zones
(SUPPLIER_TRAVEL_ZONE) soft-deletes that zone too, but only when no other
schedule of that supplier still uses it. A paused (INACTIVE) schedule
counts. The response is 204 either way.
Start and end of day locations
A schedule can say where the supplier’s working day starts and ends, for example their home. MarketBox then counts the drive from the start location to the day’s first booking, and from the last booking to the end location. The feature is off by default, and the project turns it on. A schedule carries five optional fields for it. An unset field can be absent from the response, so treat absent the same asnull.
MarketBox doesn’t geocode these locations, so send
latitude and
longitude yourself. address needs addressOneLine, streetNumber,
streetName, city, state, country and zipCode. unitNumber is
optional.
PATCH, a field you leave out keeps its stored value, and null clears
it. Cloning a schedule copies all five fields.
Two 422 refusals guard these fields:
START_END_LOCATIONS_DISABLED message names the field:
“Start and end locations are not enabled for this project, so startLocation
cannot be set”.
Sending null, or the value already stored, never causes either refusal.
A portal that sends a whole schedule back on PATCH keeps working.
Availability responses never contain a supplier’s start or end address or
coordinates. For what changes in offered times, see
Start and end of day locations.
Block time off
Blocked time has the same date,rrule and exdates rules as a schedule. In
place of weeklyTimeRanges it takes allDay or timeRanges, plus an optional
notes. A range in timeRanges with no dayOfWeek applies on every day the
rule allows.
A single day off still needs a weekly rule. Give the day as both startDate
and endDate, and leave out BYDAY:
allDay: true takes an empty or absent timeRanges. allDay: false needs at
least one range. A lunch break every weekday, except on one holiday:
FREQ, or a rule with DTSTART, is refused:
After a timezone change
When a supplier changes their profiletimezone, their rows stay in the old
zone. POST /availability-timezone/apply-profile moves every schedule and
blocked time into the profile zone, keeping wall-clock times. For its
response, the zone it picks, the rows it skips and the bookings it leaves
where they are, see
When the supplier’s timezone moves.
Travel zones
A travel zone is either a circle around a centre or a drawn area:
DRAWN zone, send travelRegions (a GeoJSON Polygon or
MultiPolygon) instead of the distance.
A zone does nothing until a schedule names it in travelZoneRef. See
Set working hours. For the whole setup in order, and how
to check a client’s address is covered, see
Set up a mobile supplier’s service area.
To change a zone, PATCH it with the changes and its current version. A stale
version is 409 VERSION_CONFLICT: re-read the zone and try again. DELETE
takes no version. Its 409 VERSION_CONFLICT means another write to the zone
landed at the same moment: re-read the zone, then decide again.
A geometry change moves your schedules’ versions. When the geometry changes,
every schedule that uses the zone is recomputed and rewritten. The response
carries coverageRecompute: { total, failed }. Re-read any schedule you cached
before you next PATCH it. A failed schedule keeps its old coverage until
it’s next saved. A rename leaves schedules alone, and the response has no
coverageRecompute.
Venues
GET /suppliers/me/locations returns the project’s active PHYSICAL and
VIRTUAL locations, sorted by name, in one response. It has no travel
settings.
To show where a booking takes place, look up its locationId with the key-only
GET /locations/{locationId}. It returns inactive
locations too, so a booking at a venue that has since closed still resolves.