Skip to main content
POST
Build a single-supplier N-session package slate (policy-driven), persisting suggestions

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 + cadence + policy knobs

packageId
string

The package to plan sessions for. serviceId, offeringId and the session count (creditCount) are resolved from it server-side.

Minimum string length: 1
Example:

"pkg_01kv7n10k0fnptwk81wkm59vj7"

locationId
string

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

Minimum string length: 1
Example:

"loc_01kv60qgs4e4nbjhzradnqtj0h"

lat

Client latitude (travel-zone branch). Provide with lng instead of locationId.

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 — it is stamped onto every returned slot so a later book-by-id satisfies the TRAVEL_ZONE address rule.

supplierId
string

Pin the plan to one supplier; only that supplier is considered.

Minimum string length: 1
Example:

"sup_01kv60qgnef2kt3pvqgwmkbzfr"

timezone
string

IANA timezone for the plan.

Minimum string length: 1
Example:

"America/Toronto"

lookAheadStartDate
string

When the recurring window starts. MUST carry a numeric UTC offset (e.g. -04:00), NOT a Z suffix.

Example:

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

rrule
string

Your PREFERRED cadence for the sessions. MUST include a bounded, positive COUNT. When cadenceFlexibility is FALLBACK or ALWAYS and no supplier can meet this exactly, denser supplier-feasible cadences come back in cadenceAlternatives instead of a 422.

Example:

"FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=8"

lookAheadDays
integer
Required range: x > 0
endDate
string
preferredTimes
object[]
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
default:3

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

Required range: x >= 0
Example:

3

persist
boolean
default:true

Persist the slate so it can be booked later by slateId. Defaults true.

Example:

true

orderId
string

The order holding the credit. With orderItemId, instead of packageId: plans the credit's remaining sessions in its own service/offering, ending at its expiresAt.

Minimum string length: 1
Example:

"ord_01kv7n10k0fnptwk81wkm59vj7"

orderItemId
string

The PACKAGE order item (credit) to plan for. Requires orderId.

Minimum string length: 1
Example:

"oi_01kv7n10k0fnptwk81wkm59vj7"

clientId
string

Optional, with orderId + orderItemId only: the client the credit must belong to. When the order is another client's, the slate is refused exactly as for an order that does not exist (400 INVALID_ORDER_REFERENCE).

Minimum string length: 1
Example:

"cli_01kv7n10k0fnptwk81wkm59vj7"

Response

Primary slate (OK), a usable partial slate, or — when cadenceFlexibility was set — bookable cadenceAlternatives (ALTERNATIVE_CADENCE)

status
enum<string>
required

OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or NO_AVAILABILITY. ALTERNATIVE_CADENCE is only reachable when this request opted in via cadenceFlexibility or guaranteeSlate — a request sending today’s body (neither set) never observes it.

Available options:
OK,
ALTERNATIVE_CADENCE,
NO_COMPLETE_SLATE,
NO_AVAILABILITY
reason
string | null
required
suggestionRequestId
string | null
required

Audit id for this suggestion request (present when persisted).

resolvableUntil
string<date-time> | null
required
primarySlate
object | null
required

The best COMPLETE single-supplier slate; book this by slateId.

alternates
object[]
required

Other bookable options beyond primarySlate, ranked best first and capped at the maxAlternates you sent. Under the default supplierPolicy of SAME_SUPPLIER these are other schedules from the SAME supplier as primarySlate; under PREFERRED or ANY they are other suppliers’ best schedules, one per supplier. Two schedules from one supplier count as different options only when they run on different weekdays, or start at least 30 minutes apart — so a supplier offering 09:00 and 09:20 gives you one option, not two. Each entry’s slateId is bookable exactly like primarySlate’s.

partial
object | null
required
searchId
string

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"

cadenceAlternatives
object[]

Complete N-session slates that fit the supplier’s real availability but do NOT follow the rrule you asked for — e.g. you requested weekly Fridays, no supplier has eight free Fridays, so this carries a Mon+Fri plan instead. Sorted by cadenceDistance, closest first, when the request carries no sessionsPerWeek target; when it does, ranked by closeness to that target first and cadenceDistance only as the tiebreaker. Always empty unless the request set cadenceFlexibility or guaranteeSlate. Each entry’s slateId is bookable exactly like primarySlate’s.

requestedCadence
string | null

The rrule this request asked for, echoed back so you can diff it against each slate’s cadenceRrule.

Example:

"FREQ=WEEKLY;BYDAY=FR;COUNT=8"