- A travel zone: the area they cover, as a circle or a drawn shape.
- An
ACTIVEschedule that names the zone: the hours they work there, and which offerings.
The supplier’s own zone or a project zone
A schedule can name one of two kinds of zone:Set it up
1
Give the supplier a timezone
A schedule’s hours are wall-clock times in its Set it on the profile once with
timezone. Leave timezone out
of the schedule and it takes the supplier’s profile timezone, then the
project’s default. When neither is set, the schedule is refused:PATCH /suppliers/me, or send timezone on
every schedule. See Times.2
Create the travel zone
A Each position is A
CIRCULAR zone is a radius around a centre:travelDistanceUnit is KM or MILES. Coverage is the straight-line
distance from the centre, not driving time.A DRAWN zone is a GeoJSON Polygon or MultiPolygon in travelRegions.
It still needs latitude and longitude, as its centre:[longitude, latitude], and each ring ends where it starts.
The API doesn’t check the polygon’s shape. An unclosed ring or swapped
coordinates is saved, and then covers the wrong place or nothing. Draw it
with a map tool, and check it with a test address afterwards (Step 4).The 201 returns the zone in data, with supplierTravelZoneId (the stz_
id) and version: 1.Each type requires its own fields and refuses the other’s. A CIRCULAR zone
without its distance is a 400:CIRCULAR zone with travelRegions is travelRegions must be null for CIRCULAR travel zones. A DRAWN zone with a distance is travelDistance must be null for DRAWN travel zones, and one without a shape is travelRegions is required for DRAWN travel zones.3
Create the schedule that uses it
Name the zone in Only real hours collide. Two schedules on different days, or one that ends
at 12:00 and one that starts at 12:00, don’t. To cover two areas on the same
morning, draw one zone that covers both, or split the hours between the
schedules.
travelZoneRef. This schedule covers Monday, Wednesday and
Friday mornings, for one offering:- The schedule is
ACTIVEunless you say otherwise. serviceOfferingIdsmust beACTIVEofferings of the supplier’s own services. Anything else is400 BAD_REQUEST,Offerings not active for this supplier: off_….- Copy the zone id from the create response, or from
GET /suppliers/me/travel-zones. A schedule that names only a zone, and no venue, doesn’t check that the zone exists. A typo saves without an error and covers nothing.
locationRefs as well as a zone. For a client’s
address, only the schedule’s own zone counts: clinic hours never become house
calls.If the project uses start and end of day locations, the schedule can also
say where the supplier’s day starts and ends, such as their home. The drive
from there to the first booking, and from the last booking back, then counts.
See Start and end of day locations.An ACTIVE schedule may not overlap another ACTIVE schedule of the same
supplier, whichever venue or zone each one names. A supplier is in one
place at a time. The second one is refused:4
Check a client's address is covered
Each check below needs only the API key, so your server or an admin tool can
run it.Search reads an index that MarketBox updates shortly after the schedule is
saved, not in the same request. Allow a short delay before you decide the
setup failed. Don’t test with
- The supplier’s profile.
GET /suppliers/{supplierId}lists the zone inlocations[], withlocationType: "TRAVEL_ZONE"and thestz_id, and the schedule inavailability.schedules[]withtravelZoneset. - Coverage of one point.
GET /suppliers?lat=43.6532&lng=-79.3832lists only suppliers whose zone contains that point. It’s the exact radius or polygon test, without availability. - Open times there.
POST /availability/supplierswith the service, the offering and the samelatandlngreturns the supplier with their open slots indays[].
servedRegions on the profile: a background
index maintains it, and its daily sweep can lag by up to a day.Search takes coordinates, not an address. Geocode the client’s address
first. See Search suppliers by availability.5
Book at the client's address
Book, or hold, with
locationType: "TRAVEL_ZONE", the supplier’s stz_ id as
locationId, the client’s latitude and longitude, and the structured
address. Search slots carry times only, so take the stz_ id from the
supplier’s locations[]. When the supplier has more than one zone, take the
one that covers the client.See Hold slots during checkout
for the full hold and convert, and
Client checkout, end to end for the
whole flow.A booking checks that the zone is the supplier’s own and isn’t deleted. It
doesn’t check that the client’s coordinates are inside it. Book only a
supplier search returned for those coordinates.Change the area later
Edit a zone
PATCH /suppliers/me/travel-zones/{travelZoneId} with the changed fields and
the zone’s current version:
version changes nothing. Re-read the zone and try again:
coverageRecompute: { total, failed }, and each of those
schedules gets a new version. Re-read a schedule before you next PATCH
it, or you’ll get 409 VERSION_CONFLICT with Schedule was modified by another writer. A failed schedule keeps its old coverage until it’s next
saved. A rename leaves the schedules alone.
Remove a zone, or stop working in it
Two deletes cascade, or fail to, in ways that are easy to miss:- Deleting a zone doesn’t touch its schedules.
DELETEon a zone that anACTIVEschedule uses succeeds with204. The schedule keeps naming the deleted zone and quietly covers no one. Setting the zone’sactivetofalsedoes the same. Delete or change the schedules first. - Deleting a schedule can delete its zone.
DELETEon a schedule whosetravelZoneRefnames one of the supplier’s own zones soft-deletes that zone too, but only when no other schedule of that supplier uses it. A paused (INACTIVE) schedule counts as a use. So the last schedule to name a zone takes the zone with it. To keep the zone, change that schedule’sstatustoINACTIVEinstead of deleting it.
Reference
Endpoints used in this guide
Errors and edge cases
See Errors for the envelope, and
Concurrency for
version.