Skip to main content
A mobile supplier delivers at the client’s address: a swim instructor at the client’s pool, a trainer at their home. Search offers them to a client only when two things exist:
  1. A travel zone: the area they cover, as a circle or a drawn shape.
  2. An ACTIVE schedule that names the zone: the hours they work there, and which offerings.
A zone with no schedule makes no one bookable. A schedule with no zone covers only the venues it names. Both are written on the supplier plane, as the signed-in supplier, from your supplier portal or the MarketBox dashboard. An API key on its own can’t create a zone or a schedule. See Sign-in and access for sign-in and the two credentials, and Availability for the full schedule rules. This guide is the setup in order, and how to check it worked.

The supplier’s own zone or a project zone

A schedule can name one of two kinds of zone:
Only the supplier’s own zone can be booked at a client’s address. Search offers a supplier whose schedule names a project zone. But a TRAVEL_ZONE booking or package booking takes the supplier’s stz_ id as its locationId. A loc_ project zone there is refused:
A hold accepts a loc_ id, and fails later. POST /holds returns 201, and the same 404 comes at convert, after the client may already have paid. Check that the id starts with stz_ before you hold.POST /availability/package-slate still returns a slate for that supplier, but booking from it fails with 409 LOCATION_UNRESOLVABLE.Give every mobile supplier a zone of their own, even when it matches a project zone.

Set it up

1

Give the supplier a timezone

A schedule’s hours are wall-clock times in its 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:
Set it on the profile once with PATCH /suppliers/me, or send timezone on every schedule. See Times.
2

Create the travel zone

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:
Each position is [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:
A 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 travelZoneRef. This schedule covers Monday, Wednesday and Friday mornings, for one offering:
  • The schedule is ACTIVE unless you say otherwise.
  • serviceOfferingIds must be ACTIVE offerings of the supplier’s own services. Anything else is 400 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.
A schedule may name venues in 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:
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.
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.
  1. The supplier’s profile. GET /suppliers/{supplierId} lists the zone in locations[], with locationType: "TRAVEL_ZONE" and the stz_ id, and the schedule in availability.schedules[] with travelZone set.
  2. Coverage of one point. GET /suppliers?lat=43.6532&lng=-79.3832 lists only suppliers whose zone contains that point. It’s the exact radius or polygon test, without availability.
  3. Open times there. POST /availability/suppliers with the service, the offering and the same lat and lng returns the supplier with their open slots in days[].
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 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:
A stale version changes nothing. Re-read the zone and try again:
A change to the shape rewrites the schedules that use the zone. The response carries 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. DELETE on a zone that an ACTIVE schedule uses succeeds with 204. The schedule keeps naming the deleted zone and quietly covers no one. Setting the zone’s active to false does the same. Delete or change the schedules first.
  • Deleting a schedule can delete its zone. DELETE on a schedule whose travelZoneRef names 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’s status to INACTIVE instead of deleting it.
To take time off inside an area without touching the schedule, block the time instead. See Block time off. For holidays, seasonal hours and a supplier who moves, see Weekly hours, exceptions and seasons.

Reference

Endpoints used in this guide

Errors and edge cases

See Errors for the envelope, and Concurrency for version.