Skip to main content
POST
List a service's packages, each with a ready-to-book slate

Authorizations

x-api-key
string
header
required

API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (*) except POST /v1/projects/{projectId}/events, which needs events:write; a key without * is refused with 403 CAPABILITY_NOT_GRANTED.

Path Parameters

projectId
string
required

The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.

Minimum string length: 1
Example:

"prj_01kv60qgnef2kt3pvqgwmkbzfr"

Body

application/json

Service + location + optional supplier and cadence

A service + a location (+ optionally a supplier and cadence).

serviceId
string
required

The service whose ACTIVE packages should be priced and planned.

Minimum string length: 1
Example:

"srv_01kq8cp17bf03t125zhakpcgyx"

locationId
string

Discovery by a stored location id. Provide this OR lat+lng+address.

Minimum string length: 1
lat

Client latitude (travel-zone branch).

Example:

43.6532

lng

Client longitude (travel-zone branch).

Example:

-79.3832

address
object

Structured client address. Required on the lat/lng (travel-zone) branch.

supplierId
string

Pin every slate to one supplier. Omit to consider all suppliers serving the location.

Minimum string length: 1
timezone
string

IANA timezone. Defaults to the project's defaultTimezone.

Minimum string length: 1
rrule
string

Cadence for every package. Omit to default to FREQ=WEEKLY;COUNT={creditCount}, derived per package from its own credit count.

Example:

"FREQ=WEEKLY;BYDAY=MO"

lookAheadStartDate
string

ISO start of the search window. Defaults to now. When provided, MUST carry a numeric UTC offset (e.g. -04:00), NOT a Z suffix.

Example:

"2026-07-09T00:00:00-04:00"

preferredTimes
object[] | null
daysOfWeek
integer[]

Weekdays sessions may fall on (0 = Sunday … 6 = Saturday). At least one weekday is required when this field is present — omit the field entirely for "any day"; an empty array is rejected. This is a HARD filter, not a preference: a weekday you leave out is removed from the supplier availability the planner sees, so no session can land on it and cadence relaxation cannot reintroduce it.

Required array length: 1 - 7 elements
Required range: 0 <= x <= 6
Example:
excludeDates
string[]

Local calendar dates (YYYY-MM-DD) that must not carry a session — a holiday, a trip. Matched against each slot's own local calendar date as the planner buckets it, not against a UTC instant. Pass each date individually; there is no range form.

Maximum array length: 90
Pattern: ^\d{4}-\d{2}-\d{2}$
Example:
sessionsPerWeek
integer

How many sessions a week you want, independent of which weekdays. A TARGET, not a cap: distinct from maxSessionsPerWeek, which bounds sessions per Monday-anchored week and applies only to direct-fill slates. The target is always SCORED — matchComponents.sessionsPerWeek reports it on every slate — but it only STEERS which slates get built when cadence relaxation actually runs: cadenceFlexibility ALWAYS, cadenceFlexibility FALLBACK once the requested cadence yields nothing, or guaranteeSlate true, which promotes NONE to FALLBACK. On the default cadenceFlexibility of NONE your rrule fixes the schedule completely, so the target is scored and reported but changes nothing about which slates come back — send it together with cadenceFlexibility FALLBACK or ALWAYS to have it steer. Where it steers, it steers the ORDER too, and that order carries the half of your preference matchScore cannot: matchComponents.sessionsPerWeek asks for AT LEAST the target, so against a target of 2 a three-a-week slate scores exactly as well as a two-a-week one. Take the results in the order they arrive; re-sorting them by matchScore throws that preference away.

Required range: 1 <= x <= 14
Example:

3

cadenceFlexibility
enum<string>
default:NONE

How hard to try when the supplier cannot meet your rrule exactly. NONE (default) is today’s behaviour: no cadence at the requested rrule means no slate. FALLBACK also returns cadenceAlternatives — complete slates at a DENSER, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri) — but only when the requested cadence yields nothing. ALWAYS returns them alongside a successful primarySlate too, so you can show "…or twice a week".

Available options:
NONE,
FALLBACK,
ALWAYS
Example:

"FALLBACK"

guaranteeSlate
boolean
default:false

Try harder before giving up. When every relaxed cadence also fails, fall back to a direct fill: all N sessions picked straight from the supplier’s openings with no recurrence rule, one per day, at the most consistent start time available. This guarantees flexibility of CADENCE, not of capacity — a supplier without N open days still yields no complete plan, and an under-filled plan is surfaced (or not) by the project’s allowPartialPackages setting via partial, exactly as it is today. Implies cadenceFlexibility FALLBACK.

Example:

true

maxCadenceAlternatives
integer
default:3

Max entries in cadenceAlternatives. Ignored when cadenceFlexibility is NONE.

Required range: 0 <= x <= 10
Example:

3

allowWeekdaySubstitution
boolean
default:true

Whether a relaxed cadence may DROP a requested weekday. Set false to keep every weekday you asked for and only ever add to them — use it when the requested day is non-negotiable (e.g. the client is only home on Fridays).

Example:

true

minGapDays
integer

Minimum whole days between consecutive sessions in a direct-fill slate. Use it to stop a dense fallback from stacking sessions on back-to-back days. It reaches only the direct fill, not any relaxed cadence-ladder rung, so a rung can still land sessions closer together than this.

Required range: 0 <= x <= 90
Example:

2

maxSessionsPerWeek
integer

Cap on sessions per Monday-anchored calendar week in a direct-fill slate — it reaches only the direct fill, not any relaxed cadence-ladder rung, so a rung built at a denser cadence can still land more sessions in a week than this. See sessionsPerWeek for the corresponding TARGET.

Required range: 0 < x <= 14
Example:

3

maxAlternates
integer

Maximum entries in alternates — same-supplier schedules or other suppliers, per your supplierPolicy. 0 returns none.

Required range: x >= 0
Example:

3

persist
boolean

Persist slates so primarySlate.slateId is bookable. Defaults to true.

Response

One entry per ACTIVE package

searchId
string
required

The id of this search, also returned as the X-MB-Search-Id header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as searchId when the client books, and in the search.rendered event when you report what you showed.

Example:

"srch_01k7q3x9h4e8rb2d6m0z5a7c1n"

data
object[]
required