Skip to main content
This page is part of Build a supplier portal. It holds the field rules for a schedule, a blocked time and a travel zone. Paths are relative to /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

  1. GET /suppliers/me/locations for the venue picker. For the area picker, GET /suppliers/me/travel-zones lists the supplier’s own travel zones, and the key-only GET /v1/projects/{projectId}/locations?locationType=TRAVEL_ZONE lists the project’s. GET /suppliers/me/locations never returns TRAVEL_ZONE locations, so a portal needs that key-only call too.
  2. Create the schedule. This one is for a venue:
    Name each venue with both its locationId and its locationType from GET /suppliers/me/locations. For an area, send travelZoneRef instead of, or as well as, locationRefs. This schedule covers one of the supplier’s own zones, for one offering only:
    travelZoneRef names 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 an ACTIVE schedule 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 own stz_ id. A loc_ project zone in its locationId is a 404 NOT_FOUND. See The supplier’s own zone or a project zone.
  3. To change it, PATCH /schedules/{scheduleId} with the changed fields and the row’s current version.
Before a schedule is saved, the API checks it. Each check below that fails is a 400:
  • rrule is FREQ=WEEKLY, with no DTSTART. INTERVAL, BYDAY and UNTIL are read. With no BYDAY, every day is allowed, so each range applies on its own dayOfWeek. To skip single dates, such as a public holiday, list them in exdates as YYYY-MM-DD.
  • In each range, startTime and endTime differ, and crossesMidnight is true exactly when startTime is later than endTime: a range that ends the next day.
  • appliesToAllOfferings: true takes no serviceOfferingIds. appliesToAllOfferings: false needs at least one.
  • Each of serviceOfferingIds is an ACTIVE offering of one of the supplier’s own services, the ones in their profile serviceIds. Anything else is 400 BAD_REQUEST naming the ids, such as “Offerings not active for this supplier: off_01kv60qge5eh59ap0gw0pqrrys”.
  • A schedule has at least one entry in locationRefs, a travelZoneRef, or both.
  • Each venue and zone exists in the project, with the type you named.
The start and end fields have two 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: an ACTIVE schedule may not overlap another ACTIVE one. 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. A DELETE can also get it, when another write lands on the row at the same moment.
Blocked time and travel zones answer a stale 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 as null. 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.
On 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:
The 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:
Any other FREQ, or a rule with DTSTART, is refused:

After a timezone change

When a supplier changes their profile timezone, 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:
For a 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.