Build a single-supplier N-session package slate (policy-driven), persisting suggestions
Builds one or more “slates” — complete N-session plans for a package — from a single supplier’s availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client’s credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit’s expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client’s order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package’s creditCount, or the credit’s remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders//package-bookings with . Returns 422 when nothing is bookable.
The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders//package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422.
The response carries a searchId (also the X-MB-Search-Id header, and the persisted suggestion request’s correlation id) and each slate its 0-based position across the whole response. Keep searchId for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: X-MB-Session-Key (an opaque key you choose, up to 64 characters) and X-MB-Client-Kind (browser, server, monitor or loadtest).
POST
/
v1
/
projects
/
{projectId}
/
availability
/
package-slate
Build a single-supplier N-session package slate (policy-driven), persisting suggestions
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
stringnumber
Client latitude (travel-zone branch). Provide with lng instead of locationId.
Example:
43.6532
lng
stringnumber
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.
Show child attributes
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[]
Show child attributes
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:
[1, 2]
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:
["2026-08-20", "2026-08-21", "2026-08-22"]
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.
Show child attributes
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.
Show child attributes
partial
object | null
required
Show child attributes
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.
Show child attributes
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"
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"MarketBox API","description":"Reference and guides for the MarketBox public API","colors":{"primary":"#0087EE","light":"#0087EE","dark":"#0087EE"},"logo":{"light":"https://mintcdn.com/marketboxinc/ajdEqdrEaJkvfx4T/logo/light.svg?fit=max\u0026auto=format\u0026n=ajdEqdrEaJkvfx4T\u0026q=85\u0026s=655948ee6454a1e06bfe0dffda47c7cc","dark":"https://mintcdn.com/marketboxinc/ajdEqdrEaJkvfx4T/logo/dark.svg?fit=max\u0026auto=format\u0026n=ajdEqdrEaJkvfx4T\u0026q=85\u0026s=54826a391e30ee9c27adf963d88a61eb"},"favicon":"https://mintcdn.com/marketboxinc/oL3tvBLJ_yQtNXOS/favicon.svg?fit=max\u0026auto=format\u0026n=oL3tvBLJ_yQtNXOS\u0026q=85\u0026s=01ed3064e8e10cbf6c9a05fae050a805","navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://app.gomarketbox.com/dashboard"}},"footer":{"socials":{"x":"https://x.com/marketboxio","linkedin":"https://linkedin.com/company/marketbox"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"marketboxinc","hasAudioNarration":false,"actualSubdomain":"marketboxinc","customDomains":["docs.gomarketbox.com"],"gitSource":{"type":"github","owner":"gomarketbox","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6aff115945eb182701d43e97","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"API reference","count":139},{"language":"default","tag":"Endpoints","count":138},{"language":"default","tag":"Guides","count":89},{"language":"default","tag":"Supplier plane","count":38},{"language":"default","tag":"Bookings","count":20},{"language":"default","tag":"Core concepts","count":14},{"language":"default","tag":"Orders","count":13},{"language":"default","tag":"Resources","count":12},{"language":"default","tag":"Suppliers","count":12},{"language":"default","tag":"Build a supplier portal","count":9}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions","slug":"/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions","pageMetadata":{"title":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions","description":"Builds one or more \"slates\" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit's expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client's order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package's creditCount, or the credit's remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable.\n\nThe rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422.\n\nThe response carries a `searchId` (also the `X-MB-Search-Id` header, and the persisted suggestion request's correlation id) and each slate its 0-based `position` across the whole response. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/package-slate","href":"/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Builds one or more “slates” — complete N-session plans for a package — from a single supplier’s availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client’s credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit’s expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client’s order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package’s creditCount, or the credit’s remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/\", \"/package-bookings with \", \". Returns 422 when nothing is bookable.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/\", \"/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response carries a \", _jsx(_components.code, {\n children: \"searchId\"\n }), \" (also the \", _jsx(_components.code, {\n children: \"X-MB-Search-Id\"\n }), \" header, and the persisted suggestion request’s correlation id) and each slate its 0-based \", _jsx(_components.code, {\n children: \"position\"\n }), \" across the whole response. Keep \", _jsx(_components.code, {\n children: \"searchId\"\n }), \" for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: \", _jsx(_components.code, {\n children: \"X-MB-Session-Key\"\n }), \" (an opaque key you choose, up to 64 characters) and \", _jsx(_components.code, {\n children: \"X-MB-Client-Kind\"\n }), \" (\", _jsx(_components.code, {\n children: \"browser\"\n }), \", \", _jsx(_components.code, {\n children: \"server\"\n }), \", \", _jsx(_components.code, {\n children: \"monitor\"\n }), \" or \", _jsx(_components.code, {\n children: \"loadtest\"\n }), \").\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions","description":"Builds one or more \"slates\" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit's expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client's order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package's creditCount, or the credit's remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable.\n\nThe rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422.\n\nThe response carries a `searchId` (also the `X-MB-Search-Id` header, and the persisted suggestion request's correlation id) and each slate its 0-based `position` across the whole response. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/package-slate","href":"/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Availability"],"summary":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions","description":"Builds one or more \"slates\" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit's expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client's order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package's creditCount, or the credit's remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable.\n\nThe rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422.\n\nThe response carries a `searchId` (also the `X-MB-Search-Id` header, and the persisted suggestion request's correlation id) and each slate its 0-based `position` across the whole response. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).","parameters":["d8aa5a8b-795f-4f22-9a3f-8436417ba467"],"requestBody":"b186b6e7-f994-49a7-9456-873cba254617","responses":{"200":"0692de1f-3ead-42b0-88d1-500e7a4b1c0e","400":"13cd0bde-9c3c-4b85-81e8-18d15a71565d","401":"7765dac0-4c61-43ba-9c72-fddd009a80f9","403":"75a4de57-b213-43d5-a074-7bf52226c854","404":"a5e2d0a3-57eb-4b0f-a00f-739baca4edab","409":"937d0734-eb94-4c90-a9f0-1b0841a6c8f9","422":"527f8efd-f07a-4a16-be5a-b4bf8774058c"},"method":"post","type":"path","servers":["7f0c0cfd-7cba-4616-861f-ca7611ae4010"],"security":["db6d1cf6-4a08-4a4c-92da-023445e576e6"],"path":"/v1/projects/{projectId}/availability/package-slate","baseUrlOptions":["https://apiv2.gomarketbox.com"],"title":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"d8aa5a8b-795f-4f22-9a3f-8436417ba467":{"schema":{"type":"string","minLength":1,"description":"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.","example":"prj_01kv60qgnef2kt3pvqgwmkbzfr","isRequired":true,"uniqueKey":"","typeLabel":"string"},"required":true,"description":"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.","name":"projectId","in":"path"}},"requestBody":{"description":"Service + location + cadence + policy knobs","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packageId":{"type":"string","minLength":1,"description":"The package to plan sessions for. serviceId, offeringId and the session count (creditCount) are resolved from it server-side.","example":"pkg_01kv7n10k0fnptwk81wkm59vj7","uniqueKey":"packageId","typeLabel":"string"},"locationId":{"type":"string","minLength":1,"description":"Discovery by a stored location id. Provide this OR lat+lng.","example":"loc_01kv60qgs4e4nbjhzradnqtj0h","uniqueKey":"locationId","typeLabel":"string"},"lat":{"oneOf":[{"type":"string","description":"Client latitude (travel-zone branch). Provide with lng instead of locationId.","example":43.6532,"uniqueKey":"lat.oneOf.0","typeLabel":"string"},{"type":"number","description":"Client latitude (travel-zone branch). Provide with lng instead of locationId.","example":43.6532,"uniqueKey":"lat.oneOf.1","typeLabel":"number"}],"uniqueKey":"lat","typeLabel":"string | number"},"lng":{"oneOf":[{"type":"string","description":"Client longitude (travel-zone branch).","example":-79.3832,"uniqueKey":"lng.oneOf.0","typeLabel":"string"},{"type":"number","description":"Client longitude (travel-zone branch).","example":-79.3832,"uniqueKey":"lng.oneOf.1","typeLabel":"number"}],"uniqueKey":"lng","typeLabel":"string | number"},"address":{"type":"object","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada","isRequired":true,"uniqueKey":"address.addressOneLine","typeLabel":"string"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10","isRequired":true,"uniqueKey":"address.streetNumber","typeLabel":"string"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St","isRequired":true,"uniqueKey":"address.streetName","typeLabel":"string"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto","isRequired":true,"uniqueKey":"address.city","typeLabel":"string"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON","isRequired":true,"uniqueKey":"address.state","typeLabel":"string"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA","isRequired":true,"uniqueKey":"address.country","typeLabel":"string"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1","isRequired":true,"uniqueKey":"address.zipCode","typeLabel":"string"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"address.unitNumber.oneOf.0","typeLabel":"string"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"address.unitNumber.oneOf.1","typeLabel":"null"}],"uniqueKey":"address.unitNumber","typeLabel":"string | null"}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"description":"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.","uniqueKey":"address","typeLabel":"object"},"supplierId":{"type":"string","minLength":1,"description":"Pin the plan to one supplier; only that supplier is considered.","example":"sup_01kv60qgnef2kt3pvqgwmkbzfr","uniqueKey":"supplierId","typeLabel":"string"},"timezone":{"type":"string","minLength":1,"description":"IANA timezone for the plan.","example":"America/Toronto","uniqueKey":"timezone","typeLabel":"string"},"lookAheadStartDate":{"type":"string","description":"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","uniqueKey":"lookAheadStartDate","typeLabel":"string"},"rrule":{"type":"string","description":"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","uniqueKey":"rrule","typeLabel":"string"},"lookAheadDays":{"type":"integer","minimum":0,"exclusiveMinimum":true,"uniqueKey":"lookAheadDays","typeLabel":"integer"},"endDate":{"type":"string","uniqueKey":"endDate","typeLabel":"string"},"preferredTimes":{"type":"array","items":{"type":"object","properties":{"startTime":{"type":"string","isRequired":true,"uniqueKey":"preferredTimes.items.[INDEX].startTime","typeLabel":"string"},"endTime":{"type":"string","isRequired":true,"uniqueKey":"preferredTimes.items.[INDEX].endTime","typeLabel":"string"}},"required":["startTime","endTime"],"uniqueKey":"preferredTimes.items.[INDEX]","typeLabel":"object"},"uniqueKey":"preferredTimes","typeLabel":"object[]"},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"daysOfWeek.items.[INDEX]","typeLabel":"integer"},"minItems":1,"maxItems":7,"description":"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.","example":[1,2],"uniqueKey":"daysOfWeek","typeLabel":"integer[]"},"excludeDates":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","uniqueKey":"excludeDates.items.[INDEX]","typeLabel":"string"},"maxItems":90,"description":"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.","example":["2026-08-20","2026-08-21","2026-08-22"],"uniqueKey":"excludeDates","typeLabel":"string[]"},"sessionsPerWeek":{"type":"integer","minimum":1,"maximum":14,"description":"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.","example":3,"uniqueKey":"sessionsPerWeek","typeLabel":"integer"},"cadenceFlexibility":{"type":"string","enum":["NONE","FALLBACK","ALWAYS"],"default":"NONE","description":"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\".","example":"FALLBACK","uniqueKey":"cadenceFlexibility","typeLabel":"enum\u003cstring>"},"guaranteeSlate":{"type":"boolean","default":false,"description":"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,"uniqueKey":"guaranteeSlate","typeLabel":"boolean"},"maxCadenceAlternatives":{"type":"integer","minimum":0,"maximum":10,"default":3,"description":"Max entries in cadenceAlternatives. Ignored when cadenceFlexibility is NONE.","example":3,"uniqueKey":"maxCadenceAlternatives","typeLabel":"integer"},"allowWeekdaySubstitution":{"type":"boolean","default":true,"description":"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,"uniqueKey":"allowWeekdaySubstitution","typeLabel":"boolean"},"minGapDays":{"type":"integer","minimum":0,"maximum":90,"description":"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.","example":2,"uniqueKey":"minGapDays","typeLabel":"integer"},"maxSessionsPerWeek":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":14,"description":"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.","example":3,"uniqueKey":"maxSessionsPerWeek","typeLabel":"integer"},"maxAlternates":{"type":"integer","minimum":0,"default":3,"description":"Maximum entries in alternates — same-supplier schedules or other suppliers, per your supplierPolicy. 0 returns none.","example":3,"uniqueKey":"maxAlternates","typeLabel":"integer"},"persist":{"type":"boolean","default":true,"description":"Persist the slate so it can be booked later by slateId. Defaults true.","example":true,"uniqueKey":"persist","typeLabel":"boolean"},"orderId":{"type":"string","minLength":1,"description":"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.","example":"ord_01kv7n10k0fnptwk81wkm59vj7","uniqueKey":"orderId","typeLabel":"string"},"orderItemId":{"type":"string","minLength":1,"description":"The PACKAGE order item (credit) to plan for. Requires orderId.","example":"oi_01kv7n10k0fnptwk81wkm59vj7","uniqueKey":"orderItemId","typeLabel":"string"},"clientId":{"type":"string","minLength":1,"description":"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).","example":"cli_01kv7n10k0fnptwk81wkm59vj7","uniqueKey":"clientId","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"packageId":"pkg_01kv7n10k0fnptwk81wkm59vj7","locationId":"loc_01kv60qgs4e4nbjhzradnqtj0h","lat":43.6532,"lng":-79.3832,"supplierId":"sup_01kv60qgnef2kt3pvqgwmkbzfr","timezone":"America/Toronto","lookAheadStartDate":"2026-07-09T00:00:00-04:00","rrule":"FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=8","lookAheadDays":1,"endDate":"\u003cstring>","preferredTimes":[{"startTime":"\u003cstring>","endTime":"\u003cstring>"}],"daysOfWeek":[1,2],"excludeDates":["2026-08-20","2026-08-21","2026-08-22"],"sessionsPerWeek":3,"cadenceFlexibility":"FALLBACK","guaranteeSlate":true,"maxCadenceAlternatives":3,"allowWeekdaySubstitution":true,"minGapDays":2,"maxSessionsPerWeek":3,"maxAlternates":3,"persist":true,"orderId":"ord_01kv7n10k0fnptwk81wkm59vj7","orderItemId":"oi_01kv7n10k0fnptwk81wkm59vj7","clientId":"cli_01kv7n10k0fnptwk81wkm59vj7"}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"0692de1f-3ead-42b0-88d1-500e7a4b1c0e":{"description":"Primary slate (OK), a usable partial slate, or — when cadenceFlexibility was set — bookable cadenceAlternatives (ALTERNATIVE_CADENCE)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["OK","ALTERNATIVE_CADENCE","NO_COMPLETE_SLATE","NO_AVAILABILITY"],"description":"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.","isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"reason":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"reason.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"reason.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"reason","typeLabel":"string | null"},"suggestionRequestId":{"oneOf":[{"type":"string","description":"Audit id for this suggestion request (present when persisted).","isRequired":true,"uniqueKey":"suggestionRequestId.oneOf.0","typeLabel":"string"},{"type":"null","description":"Audit id for this suggestion request (present when persisted).","isRequired":true,"uniqueKey":"suggestionRequestId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"suggestionRequestId","typeLabel":"string | null"},"resolvableUntil":{"oneOf":[{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"resolvableUntil.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","isRequired":true,"uniqueKey":"resolvableUntil.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"resolvableUntil","typeLabel":"string\u003cdate-time> | null"},"primarySlate":{"oneOf":[{"type":"object","properties":{"slateId":{"type":"string","description":"Pass this to POST .../package-bookings to book the whole plan.","example":"slate_01kx16ejsqffc9rbgdcc591w2p","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slateId","typeLabel":"string"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.supplierId","typeLabel":"string"},"completeness":{"type":"string","enum":["COMPLETE","PARTIAL"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.completeness","typeLabel":"enum\u003cstring>"},"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"How many sessions were requested (the package's creditCount).","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"description":"How many of the requested sessions the plan could fill.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.sessionsFilled","typeLabel":"integer"},"startTimeConsistencyPercent":{"type":"number","minimum":0,"maximum":100,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.startTimeConsistencyPercent","typeLabel":"number"},"totalTravelTimeMins":{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.totalTravelTimeMins","typeLabel":"number"},"slots":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string","description":"Id of one session; pass a subset of these as slotIds to cherry-pick.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].slotId","typeLabel":"string"},"sessionIndex":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"1-based index of this session within the slate.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].sessionIndex","typeLabel":"integer"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].supplierId","typeLabel":"string"},"serviceId":{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].serviceId","typeLabel":"string"},"offeringId":{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].offeringId","typeLabel":"string"},"bookingStartUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].bookingStartUtc","typeLabel":"string\u003cdate-time>"},"bookingEndUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].bookingEndUtc","typeLabel":"string\u003cdate-time>"},"bookingTz":{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].bookingTz","typeLabel":"string"},"locationType":{"type":"string","enum":["PHYSICAL","VIRTUAL","TRAVEL_ZONE"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].locationType","typeLabel":"enum\u003cstring>"},"locationId":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].locationId.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].locationId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].locationId","typeLabel":"string | null"},"latitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].latitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].latitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].latitude","typeLabel":"number | null"},"longitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].longitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].longitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].longitude","typeLabel":"number | null"},"address":{"oneOf":[{"type":"object","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.addressOneLine","typeLabel":"string"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.streetNumber","typeLabel":"string"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.streetName","typeLabel":"string"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.city","typeLabel":"string"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.state","typeLabel":"string"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.country","typeLabel":"string"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.zipCode","typeLabel":"string"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.0","typeLabel":"string"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.1","typeLabel":"null"}],"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0.unitNumber","typeLabel":"string | null"}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].address","typeLabel":"object | null"},"travelTimeMins":{"oneOf":[{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].travelTimeMins.oneOf.0","typeLabel":"number"},{"type":"null","minimum":0,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].travelTimeMins.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].travelTimeMins","typeLabel":"number | null"},"capacity":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].capacity","typeLabel":"integer"},"reservationStatus":{"type":"string","enum":["FREE","HELD","CONVERTED","RELEASED"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX].reservationStatus","typeLabel":"enum\u003cstring>"}},"required":["slotId","sessionIndex","supplierId","serviceId","offeringId","bookingStartUtc","bookingEndUtc","bookingTz","locationType","locationId","latitude","longitude","address","travelTimeMins","capacity","reservationStatus"],"uniqueKey":"primarySlate.oneOf.0.slots.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.slots","typeLabel":"object[]"},"matchNotes":{"type":"array","items":{"oneOf":[{"type":"object","description":"This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SUPPLIER_UNAVAILABLE_WEEK"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.openingsInPool","typeLabel":"integer"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays","typeLabel":"integer[]"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool","supplierWorkdays"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.0","typeLabel":"object"},{"type":"object","description":"Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_EXCLUDED_BY_FILTERS"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.sessionsTargeted","typeLabel":"integer"},"filter":{"type":"string","enum":["daysOfWeek","excludeDates"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.filter","typeLabel":"enum\u003cstring>"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays","typeLabel":"integer[]"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays","typeLabel":"integer[]"},"excludedDates":{"type":"array","items":{"type":"string","uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates.items.[INDEX]","typeLabel":"string"},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates","typeLabel":"string[]"}},"required":["sessionsPlaced","sessionsTargeted","filter","supplierWorkdays"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.1","typeLabel":"object"},{"type":"object","description":"This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_SUPPLY_INSUFFICIENT"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence.openingsInPool","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.2","typeLabel":"object"},{"type":"object","description":"This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_CAPPED"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.sessionsTargeted","typeLabel":"integer"},"cap":{"type":"string","enum":["maxSessionsPerWeek","minGapDays"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.cap","typeLabel":"enum\u003cstring>"},"capValue":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.capValue","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","cap","capValue"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.3","typeLabel":"object"},{"type":"object","description":"This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_EXHAUSTED"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.4.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.4.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.4.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.4.evidence.sessionsRequested","typeLabel":"integer"},"sessionsPlacedBefore":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.4.evidence.sessionsPlacedBefore","typeLabel":"integer"}},"required":["sessionsRequested","sessionsPlacedBefore"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.4.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.4","typeLabel":"object"},{"type":"object","description":"This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["CADENCE_RELAXED"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["cadence"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.cadenceRelaxation","typeLabel":"enum\u003cstring>"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays","typeLabel":"integer[]"},"actualDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.actualDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.actualDays","typeLabel":"integer[]"}},"required":["cadenceRelaxation"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.5","typeLabel":"object"},{"type":"object","description":"These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_OUTSIDE_PREFERRED_TIMES"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["timeOfDay"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionIndexes":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes.items.[INDEX]","typeLabel":"integer"},"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes","typeLabel":"integer[]"},"localTimes":{"type":"array","items":{"type":"string","uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.localTimes.items.[INDEX]","typeLabel":"string"},"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.localTimes","typeLabel":"string[]"}},"required":["sessionIndexes","localTimes"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.6","typeLabel":"object"},{"type":"object","description":"The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["FIRST_SESSION_LATE"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["startDate"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"firstSessionDate":{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.firstSessionDate","typeLabel":"string"},"windowStartDate":{"type":"string","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.windowStartDate","typeLabel":"string"},"dayOffset":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.dayOffset","typeLabel":"integer"},"earlierSupplyExisted":{"type":"boolean","description":"TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.earlierSupplyExisted","typeLabel":"boolean"}},"required":["firstSessionDate","windowStartDate","dayOffset","earlierSupplyExisted"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.7","typeLabel":"object"},{"type":"object","description":"Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1.","required":["code","evidence"],"properties":{"code":{"type":"string","enum":["PACKAGE_UNDERFILLED"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.8.code","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.8.evidence.sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.8.evidence.sessionsFilled","typeLabel":"integer"}},"required":["sessionsRequested","sessionsFilled"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.8.evidence","typeLabel":"object"}},"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX].oneOf.8","typeLabel":"object"}],"uniqueKey":"primarySlate.oneOf.0.matchNotes.items.[INDEX]","typeLabel":"object"},"description":"Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchNotes","typeLabel":"object[]"},"matchScore":{"type":"number","minimum":0,"maximum":1,"description":"How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.","example":1,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.matchScore","typeLabel":"number"},"position":{"type":"integer","minimum":0,"description":"0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.","example":0,"uniqueKey":"primarySlate.oneOf.0.position","typeLabel":"integer"},"cadenceRrule":{"oneOf":[{"type":"string","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"primarySlate.oneOf.0.cadenceRrule.oneOf.0","typeLabel":"string"},{"type":"null","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"primarySlate.oneOf.0.cadenceRrule.oneOf.1","typeLabel":"null"}],"uniqueKey":"primarySlate.oneOf.0.cadenceRrule","typeLabel":"string | null"},"matchesRequestedCadence":{"type":"boolean","description":"True when cadenceRrule is the rrule you asked for.","example":false,"uniqueKey":"primarySlate.oneOf.0.matchesRequestedCadence","typeLabel":"boolean"},"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","uniqueKey":"primarySlate.oneOf.0.cadenceRelaxation","typeLabel":"enum\u003cstring>"},"cadenceDistance":{"type":"integer","minimum":0,"description":"How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.","example":2,"uniqueKey":"primarySlate.oneOf.0.cadenceDistance","typeLabel":"integer"},"cadenceSummary":{"type":"object","properties":{"requested":{"oneOf":[{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.requested.oneOf.0","typeLabel":"integer"},{"type":"null","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.requested.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.requested","typeLabel":"integer | null"},"peak":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).","example":4,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.peak","typeLabel":"integer"},"average":{"type":"number","minimum":0,"description":"Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.","example":2.25,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.average","typeLabel":"number"},"byWeek":{"type":"array","items":{"type":"object","properties":{"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) that starts this week.","example":"2026-09-14","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.byWeek.items.[INDEX].weekStart","typeLabel":"string"},"sessions":{"type":"integer","minimum":0,"description":"Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.","example":0,"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.byWeek.items.[INDEX].sessions","typeLabel":"integer"}},"required":["weekStart","sessions"],"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.byWeek.items.[INDEX]","typeLabel":"object"},"minItems":1,"description":"Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.cadenceSummary.byWeek","typeLabel":"object[]"}},"required":["requested","peak","average","byWeek"],"description":"How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like.","uniqueKey":"primarySlate.oneOf.0.cadenceSummary","typeLabel":"object"},"advice":{"type":"object","properties":{"code":{"type":"string","enum":["LATER_START_IMPROVES_CADENCE"],"isRequired":true,"uniqueKey":"primarySlate.oneOf.0.advice.code","typeLabel":"enum\u003cstring>"},"earliestSustainedWeek":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.","example":"2026-09-14","isRequired":true,"uniqueKey":"primarySlate.oneOf.0.advice.earliestSustainedWeek","typeLabel":"string"}},"required":["code","earliestSustainedWeek"],"description":"An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built.","uniqueKey":"primarySlate.oneOf.0.advice","typeLabel":"object"},"matchComponents":{"type":"object","properties":{"startDate":{"type":"number","minimum":0,"maximum":1,"description":"How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands.","uniqueKey":"primarySlate.oneOf.0.matchComponents.startDate","typeLabel":"number"},"timeOfDay":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall at a preferred time of day.","uniqueKey":"primarySlate.oneOf.0.matchComponents.timeOfDay","typeLabel":"number"},"daysOfWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall on a requested weekday.","uniqueKey":"primarySlate.oneOf.0.matchComponents.daysOfWeek","typeLabel":"number"},"sessionsPerWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore.","uniqueKey":"primarySlate.oneOf.0.matchComponents.sessionsPerWeek","typeLabel":"number"},"cadence":{"type":"number","minimum":0,"maximum":1,"description":"1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule.","uniqueKey":"primarySlate.oneOf.0.matchComponents.cadence","typeLabel":"number"}},"description":"How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report.","uniqueKey":"primarySlate.oneOf.0.matchComponents","typeLabel":"object"}},"required":["slateId","supplierId","completeness","sessionsRequested","sessionsFilled","startTimeConsistencyPercent","totalTravelTimeMins","slots","matchNotes","matchScore"],"description":"The best COMPLETE single-supplier slate; book this by slateId.","isRequired":true,"uniqueKey":"primarySlate.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"slateId":{"type":"string","description":"Pass this to POST .../package-bookings to book the whole plan.","example":"slate_01kx16ejsqffc9rbgdcc591w2p"},"supplierId":{"type":"string"},"completeness":{"type":"string","enum":["COMPLETE","PARTIAL"]},"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"How many sessions were requested (the package's creditCount)."},"sessionsFilled":{"type":"integer","minimum":0,"description":"How many of the requested sessions the plan could fill."},"startTimeConsistencyPercent":{"type":"number","minimum":0,"maximum":100},"totalTravelTimeMins":{"type":"number","minimum":0},"slots":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string","description":"Id of one session; pass a subset of these as slotIds to cherry-pick."},"sessionIndex":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"1-based index of this session within the slate."},"supplierId":{"type":"string"},"serviceId":{"type":"string"},"offeringId":{"type":"string"},"bookingStartUtc":{"type":"string","format":"date-time"},"bookingEndUtc":{"type":"string","format":"date-time"},"bookingTz":{"type":"string"},"locationType":{"type":"string","enum":["PHYSICAL","VIRTUAL","TRAVEL_ZONE"]},"locationId":{"oneOf":[{"type":"string"},{"type":"null"}]},"latitude":{"oneOf":[{"type":"number"},{"type":"null"}]},"longitude":{"oneOf":[{"type":"number"},{"type":"null"}]},"address":{"oneOf":[{"type":"object","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"]},{"type":"null","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"]}]},"travelTimeMins":{"oneOf":[{"type":"number","minimum":0},{"type":"null","minimum":0}]},"capacity":{"type":"integer","minimum":0,"exclusiveMinimum":true},"reservationStatus":{"type":"string","enum":["FREE","HELD","CONVERTED","RELEASED"]}},"required":["slotId","sessionIndex","supplierId","serviceId","offeringId","bookingStartUtc","bookingEndUtc","bookingTz","locationType","locationId","latitude","longitude","address","travelTimeMins","capacity","reservationStatus"]}},"position":{"type":"integer","minimum":0,"description":"0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.","example":0},"cadenceRrule":{"oneOf":[{"type":"string","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"},{"type":"null","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"}]},"matchesRequestedCadence":{"type":"boolean","description":"True when cadenceRrule is the rrule you asked for.","example":false},"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."},"cadenceDistance":{"type":"integer","minimum":0,"description":"How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.","example":2},"cadenceSummary":{"type":"object","properties":{"requested":{"oneOf":[{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4},{"type":"null","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4}]},"peak":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).","example":4},"average":{"type":"number","minimum":0,"description":"Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.","example":2.25},"byWeek":{"type":"array","items":{"type":"object","properties":{"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) that starts this week.","example":"2026-09-14"},"sessions":{"type":"integer","minimum":0,"description":"Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.","example":0}},"required":["weekStart","sessions"]},"minItems":1,"description":"Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."}},"required":["requested","peak","average","byWeek"],"description":"How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."},"matchNotes":{"type":"array","items":{"oneOf":[{"type":"object","description":"This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SUPPLIER_UNAVAILABLE_WEEK"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool","supplierWorkdays"]}}},{"type":"object","description":"Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_EXCLUDED_BY_FILTERS"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"filter":{"type":"string","enum":["daysOfWeek","excludeDates"]},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."},"excludedDates":{"type":"array","items":{"type":"string"}}},"required":["sessionsPlaced","sessionsTargeted","filter","supplierWorkdays"]}}},{"type":"object","description":"This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_SUPPLY_INSUFFICIENT"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool"]}}},{"type":"object","description":"This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_CAPPED"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"cap":{"type":"string","enum":["maxSessionsPerWeek","minGapDays"]},"capValue":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["sessionsPlaced","sessionsTargeted","cap","capValue"]}}},{"type":"object","description":"This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_EXHAUSTED"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true},"sessionsPlacedBefore":{"type":"integer","minimum":0}},"required":["sessionsRequested","sessionsPlacedBefore"]}}},{"type":"object","description":"This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["CADENCE_RELAXED"]},"component":{"type":"string","enum":["cadence"]},"evidence":{"type":"object","properties":{"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."},"actualDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."}},"required":["cadenceRelaxation"]}}},{"type":"object","description":"These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_OUTSIDE_PREFERRED_TIMES"]},"component":{"type":"string","enum":["timeOfDay"]},"evidence":{"type":"object","properties":{"sessionIndexes":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"localTimes":{"type":"array","items":{"type":"string"}}},"required":["sessionIndexes","localTimes"]}}},{"type":"object","description":"The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["FIRST_SESSION_LATE"]},"component":{"type":"string","enum":["startDate"]},"evidence":{"type":"object","properties":{"firstSessionDate":{"type":"string"},"windowStartDate":{"type":"string"},"dayOffset":{"type":"integer","minimum":0},"earlierSupplyExisted":{"type":"boolean","description":"TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."}},"required":["firstSessionDate","windowStartDate","dayOffset","earlierSupplyExisted"]}}},{"type":"object","description":"Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1.","required":["code","evidence"],"properties":{"code":{"type":"string","enum":["PACKAGE_UNDERFILLED"]},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true},"sessionsFilled":{"type":"integer","minimum":0}},"required":["sessionsRequested","sessionsFilled"]}}}]},"description":"Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."},"advice":{"type":"object","properties":{"code":{"type":"string","enum":["LATER_START_IMPROVES_CADENCE"]},"earliestSustainedWeek":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.","example":"2026-09-14"}},"required":["code","earliestSustainedWeek"],"description":"An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."},"matchScore":{"type":"number","minimum":0,"maximum":1,"description":"How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.","example":1},"matchComponents":{"type":"object","properties":{"startDate":{"type":"number","minimum":0,"maximum":1,"description":"How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."},"timeOfDay":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall at a preferred time of day."},"daysOfWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall on a requested weekday."},"sessionsPerWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."},"cadence":{"type":"number","minimum":0,"maximum":1,"description":"1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."}},"description":"How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."}},"required":["slateId","supplierId","completeness","sessionsRequested","sessionsFilled","startTimeConsistencyPercent","totalTravelTimeMins","slots","matchNotes","matchScore"],"description":"The best COMPLETE single-supplier slate; book this by slateId.","isRequired":true,"uniqueKey":"primarySlate.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"primarySlate","typeLabel":"object | null"},"alternates":{"type":"array","items":{"type":"object","properties":{"slateId":{"type":"string","description":"Pass this to POST .../package-bookings to book the whole plan.","example":"slate_01kx16ejsqffc9rbgdcc591w2p","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slateId","typeLabel":"string"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].supplierId","typeLabel":"string"},"completeness":{"type":"string","enum":["COMPLETE","PARTIAL"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].completeness","typeLabel":"enum\u003cstring>"},"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"How many sessions were requested (the package's creditCount).","isRequired":true,"uniqueKey":"alternates.items.[INDEX].sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"description":"How many of the requested sessions the plan could fill.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].sessionsFilled","typeLabel":"integer"},"startTimeConsistencyPercent":{"type":"number","minimum":0,"maximum":100,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].startTimeConsistencyPercent","typeLabel":"number"},"totalTravelTimeMins":{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].totalTravelTimeMins","typeLabel":"number"},"slots":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string","description":"Id of one session; pass a subset of these as slotIds to cherry-pick.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].slotId","typeLabel":"string"},"sessionIndex":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"1-based index of this session within the slate.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].sessionIndex","typeLabel":"integer"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].supplierId","typeLabel":"string"},"serviceId":{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].serviceId","typeLabel":"string"},"offeringId":{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].offeringId","typeLabel":"string"},"bookingStartUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].bookingStartUtc","typeLabel":"string\u003cdate-time>"},"bookingEndUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].bookingEndUtc","typeLabel":"string\u003cdate-time>"},"bookingTz":{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].bookingTz","typeLabel":"string"},"locationType":{"type":"string","enum":["PHYSICAL","VIRTUAL","TRAVEL_ZONE"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].locationType","typeLabel":"enum\u003cstring>"},"locationId":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].locationId.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].locationId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].locationId","typeLabel":"string | null"},"latitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].latitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].latitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].latitude","typeLabel":"number | null"},"longitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].longitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].longitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].longitude","typeLabel":"number | null"},"address":{"oneOf":[{"type":"object","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.addressOneLine","typeLabel":"string"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.streetNumber","typeLabel":"string"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.streetName","typeLabel":"string"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.city","typeLabel":"string"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.state","typeLabel":"string"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.country","typeLabel":"string"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1","isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.zipCode","typeLabel":"string"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.0","typeLabel":"string"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.1","typeLabel":"null"}],"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0.unitNumber","typeLabel":"string | null"}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].address","typeLabel":"object | null"},"travelTimeMins":{"oneOf":[{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].travelTimeMins.oneOf.0","typeLabel":"number"},{"type":"null","minimum":0,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].travelTimeMins.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].travelTimeMins","typeLabel":"number | null"},"capacity":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].capacity","typeLabel":"integer"},"reservationStatus":{"type":"string","enum":["FREE","HELD","CONVERTED","RELEASED"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX].reservationStatus","typeLabel":"enum\u003cstring>"}},"required":["slotId","sessionIndex","supplierId","serviceId","offeringId","bookingStartUtc","bookingEndUtc","bookingTz","locationType","locationId","latitude","longitude","address","travelTimeMins","capacity","reservationStatus"],"uniqueKey":"alternates.items.[INDEX].slots.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"alternates.items.[INDEX].slots","typeLabel":"object[]"},"matchNotes":{"type":"array","items":{"oneOf":[{"type":"object","description":"This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SUPPLIER_UNAVAILABLE_WEEK"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.openingsInPool","typeLabel":"integer"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays","typeLabel":"integer[]"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool","supplierWorkdays"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.0","typeLabel":"object"},{"type":"object","description":"Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_EXCLUDED_BY_FILTERS"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.sessionsTargeted","typeLabel":"integer"},"filter":{"type":"string","enum":["daysOfWeek","excludeDates"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.filter","typeLabel":"enum\u003cstring>"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays","typeLabel":"integer[]"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays","typeLabel":"integer[]"},"excludedDates":{"type":"array","items":{"type":"string","uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates.items.[INDEX]","typeLabel":"string"},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates","typeLabel":"string[]"}},"required":["sessionsPlaced","sessionsTargeted","filter","supplierWorkdays"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.1","typeLabel":"object"},{"type":"object","description":"This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_SUPPLY_INSUFFICIENT"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence.openingsInPool","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.2","typeLabel":"object"},{"type":"object","description":"This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_CAPPED"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.sessionsTargeted","typeLabel":"integer"},"cap":{"type":"string","enum":["maxSessionsPerWeek","minGapDays"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.cap","typeLabel":"enum\u003cstring>"},"capValue":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.capValue","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","cap","capValue"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.3","typeLabel":"object"},{"type":"object","description":"This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_EXHAUSTED"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.evidence.sessionsRequested","typeLabel":"integer"},"sessionsPlacedBefore":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.evidence.sessionsPlacedBefore","typeLabel":"integer"}},"required":["sessionsRequested","sessionsPlacedBefore"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.4","typeLabel":"object"},{"type":"object","description":"This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["CADENCE_RELAXED"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["cadence"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.cadenceRelaxation","typeLabel":"enum\u003cstring>"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays","typeLabel":"integer[]"},"actualDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.actualDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.actualDays","typeLabel":"integer[]"}},"required":["cadenceRelaxation"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.5","typeLabel":"object"},{"type":"object","description":"These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_OUTSIDE_PREFERRED_TIMES"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["timeOfDay"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionIndexes":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes.items.[INDEX]","typeLabel":"integer"},"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes","typeLabel":"integer[]"},"localTimes":{"type":"array","items":{"type":"string","uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.localTimes.items.[INDEX]","typeLabel":"string"},"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.localTimes","typeLabel":"string[]"}},"required":["sessionIndexes","localTimes"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.6","typeLabel":"object"},{"type":"object","description":"The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["FIRST_SESSION_LATE"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["startDate"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"firstSessionDate":{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.firstSessionDate","typeLabel":"string"},"windowStartDate":{"type":"string","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.windowStartDate","typeLabel":"string"},"dayOffset":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.dayOffset","typeLabel":"integer"},"earlierSupplyExisted":{"type":"boolean","description":"TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.earlierSupplyExisted","typeLabel":"boolean"}},"required":["firstSessionDate","windowStartDate","dayOffset","earlierSupplyExisted"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.7","typeLabel":"object"},{"type":"object","description":"Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1.","required":["code","evidence"],"properties":{"code":{"type":"string","enum":["PACKAGE_UNDERFILLED"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.code","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.evidence.sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.evidence.sessionsFilled","typeLabel":"integer"}},"required":["sessionsRequested","sessionsFilled"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.evidence","typeLabel":"object"}},"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX].oneOf.8","typeLabel":"object"}],"uniqueKey":"alternates.items.[INDEX].matchNotes.items.[INDEX]","typeLabel":"object"},"description":"Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchNotes","typeLabel":"object[]"},"matchScore":{"type":"number","minimum":0,"maximum":1,"description":"How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.","example":1,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].matchScore","typeLabel":"number"},"position":{"type":"integer","minimum":0,"description":"0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.","example":0,"uniqueKey":"alternates.items.[INDEX].position","typeLabel":"integer"},"cadenceRrule":{"oneOf":[{"type":"string","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"alternates.items.[INDEX].cadenceRrule.oneOf.0","typeLabel":"string"},{"type":"null","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"alternates.items.[INDEX].cadenceRrule.oneOf.1","typeLabel":"null"}],"uniqueKey":"alternates.items.[INDEX].cadenceRrule","typeLabel":"string | null"},"matchesRequestedCadence":{"type":"boolean","description":"True when cadenceRrule is the rrule you asked for.","example":false,"uniqueKey":"alternates.items.[INDEX].matchesRequestedCadence","typeLabel":"boolean"},"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","uniqueKey":"alternates.items.[INDEX].cadenceRelaxation","typeLabel":"enum\u003cstring>"},"cadenceDistance":{"type":"integer","minimum":0,"description":"How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.","example":2,"uniqueKey":"alternates.items.[INDEX].cadenceDistance","typeLabel":"integer"},"cadenceSummary":{"type":"object","properties":{"requested":{"oneOf":[{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.requested.oneOf.0","typeLabel":"integer"},{"type":"null","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.requested.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.requested","typeLabel":"integer | null"},"peak":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).","example":4,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.peak","typeLabel":"integer"},"average":{"type":"number","minimum":0,"description":"Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.","example":2.25,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.average","typeLabel":"number"},"byWeek":{"type":"array","items":{"type":"object","properties":{"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) that starts this week.","example":"2026-09-14","isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.byWeek.items.[INDEX].weekStart","typeLabel":"string"},"sessions":{"type":"integer","minimum":0,"description":"Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.","example":0,"isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.byWeek.items.[INDEX].sessions","typeLabel":"integer"}},"required":["weekStart","sessions"],"uniqueKey":"alternates.items.[INDEX].cadenceSummary.byWeek.items.[INDEX]","typeLabel":"object"},"minItems":1,"description":"Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array.","isRequired":true,"uniqueKey":"alternates.items.[INDEX].cadenceSummary.byWeek","typeLabel":"object[]"}},"required":["requested","peak","average","byWeek"],"description":"How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like.","uniqueKey":"alternates.items.[INDEX].cadenceSummary","typeLabel":"object"},"advice":{"type":"object","properties":{"code":{"type":"string","enum":["LATER_START_IMPROVES_CADENCE"],"isRequired":true,"uniqueKey":"alternates.items.[INDEX].advice.code","typeLabel":"enum\u003cstring>"},"earliestSustainedWeek":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.","example":"2026-09-14","isRequired":true,"uniqueKey":"alternates.items.[INDEX].advice.earliestSustainedWeek","typeLabel":"string"}},"required":["code","earliestSustainedWeek"],"description":"An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built.","uniqueKey":"alternates.items.[INDEX].advice","typeLabel":"object"},"matchComponents":{"type":"object","properties":{"startDate":{"type":"number","minimum":0,"maximum":1,"description":"How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands.","uniqueKey":"alternates.items.[INDEX].matchComponents.startDate","typeLabel":"number"},"timeOfDay":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall at a preferred time of day.","uniqueKey":"alternates.items.[INDEX].matchComponents.timeOfDay","typeLabel":"number"},"daysOfWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall on a requested weekday.","uniqueKey":"alternates.items.[INDEX].matchComponents.daysOfWeek","typeLabel":"number"},"sessionsPerWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore.","uniqueKey":"alternates.items.[INDEX].matchComponents.sessionsPerWeek","typeLabel":"number"},"cadence":{"type":"number","minimum":0,"maximum":1,"description":"1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule.","uniqueKey":"alternates.items.[INDEX].matchComponents.cadence","typeLabel":"number"}},"description":"How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report.","uniqueKey":"alternates.items.[INDEX].matchComponents","typeLabel":"object"}},"required":["slateId","supplierId","completeness","sessionsRequested","sessionsFilled","startTimeConsistencyPercent","totalTravelTimeMins","slots","matchNotes","matchScore"],"uniqueKey":"alternates.items.[INDEX]","typeLabel":"object"},"description":"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.","isRequired":true,"uniqueKey":"alternates","typeLabel":"object[]"},"partial":{"oneOf":[{"type":"object","properties":{"slateId":{"type":"string","description":"Pass this to POST .../package-bookings to book the whole plan.","example":"slate_01kx16ejsqffc9rbgdcc591w2p","isRequired":true,"uniqueKey":"partial.oneOf.0.slateId","typeLabel":"string"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.supplierId","typeLabel":"string"},"completeness":{"type":"string","enum":["COMPLETE","PARTIAL"],"isRequired":true,"uniqueKey":"partial.oneOf.0.completeness","typeLabel":"enum\u003cstring>"},"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"How many sessions were requested (the package's creditCount).","isRequired":true,"uniqueKey":"partial.oneOf.0.sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"description":"How many of the requested sessions the plan could fill.","isRequired":true,"uniqueKey":"partial.oneOf.0.sessionsFilled","typeLabel":"integer"},"startTimeConsistencyPercent":{"type":"number","minimum":0,"maximum":100,"isRequired":true,"uniqueKey":"partial.oneOf.0.startTimeConsistencyPercent","typeLabel":"number"},"totalTravelTimeMins":{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"partial.oneOf.0.totalTravelTimeMins","typeLabel":"number"},"slots":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string","description":"Id of one session; pass a subset of these as slotIds to cherry-pick.","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].slotId","typeLabel":"string"},"sessionIndex":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"1-based index of this session within the slate.","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].sessionIndex","typeLabel":"integer"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].supplierId","typeLabel":"string"},"serviceId":{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].serviceId","typeLabel":"string"},"offeringId":{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].offeringId","typeLabel":"string"},"bookingStartUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].bookingStartUtc","typeLabel":"string\u003cdate-time>"},"bookingEndUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].bookingEndUtc","typeLabel":"string\u003cdate-time>"},"bookingTz":{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].bookingTz","typeLabel":"string"},"locationType":{"type":"string","enum":["PHYSICAL","VIRTUAL","TRAVEL_ZONE"],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].locationType","typeLabel":"enum\u003cstring>"},"locationId":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].locationId.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].locationId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].locationId","typeLabel":"string | null"},"latitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].latitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].latitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].latitude","typeLabel":"number | null"},"longitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].longitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].longitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].longitude","typeLabel":"number | null"},"address":{"oneOf":[{"type":"object","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.addressOneLine","typeLabel":"string"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.streetNumber","typeLabel":"string"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.streetName","typeLabel":"string"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.city","typeLabel":"string"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.state","typeLabel":"string"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.country","typeLabel":"string"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1","isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.zipCode","typeLabel":"string"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.0","typeLabel":"string"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.1","typeLabel":"null"}],"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0.unitNumber","typeLabel":"string | null"}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].address","typeLabel":"object | null"},"travelTimeMins":{"oneOf":[{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].travelTimeMins.oneOf.0","typeLabel":"number"},{"type":"null","minimum":0,"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].travelTimeMins.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].travelTimeMins","typeLabel":"number | null"},"capacity":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].capacity","typeLabel":"integer"},"reservationStatus":{"type":"string","enum":["FREE","HELD","CONVERTED","RELEASED"],"isRequired":true,"uniqueKey":"partial.oneOf.0.slots.items.[INDEX].reservationStatus","typeLabel":"enum\u003cstring>"}},"required":["slotId","sessionIndex","supplierId","serviceId","offeringId","bookingStartUtc","bookingEndUtc","bookingTz","locationType","locationId","latitude","longitude","address","travelTimeMins","capacity","reservationStatus"],"uniqueKey":"partial.oneOf.0.slots.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"partial.oneOf.0.slots","typeLabel":"object[]"},"matchNotes":{"type":"array","items":{"oneOf":[{"type":"object","description":"This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SUPPLIER_UNAVAILABLE_WEEK"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.openingsInPool","typeLabel":"integer"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays","typeLabel":"integer[]"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool","supplierWorkdays"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.0","typeLabel":"object"},{"type":"object","description":"Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_EXCLUDED_BY_FILTERS"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.sessionsTargeted","typeLabel":"integer"},"filter":{"type":"string","enum":["daysOfWeek","excludeDates"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.filter","typeLabel":"enum\u003cstring>"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays","typeLabel":"integer[]"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays","typeLabel":"integer[]"},"excludedDates":{"type":"array","items":{"type":"string","uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates.items.[INDEX]","typeLabel":"string"},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates","typeLabel":"string[]"}},"required":["sessionsPlaced","sessionsTargeted","filter","supplierWorkdays"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.1","typeLabel":"object"},{"type":"object","description":"This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_SUPPLY_INSUFFICIENT"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence.openingsInPool","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.2","typeLabel":"object"},{"type":"object","description":"This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_CAPPED"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.sessionsTargeted","typeLabel":"integer"},"cap":{"type":"string","enum":["maxSessionsPerWeek","minGapDays"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.cap","typeLabel":"enum\u003cstring>"},"capValue":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence.capValue","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","cap","capValue"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.3","typeLabel":"object"},{"type":"object","description":"This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_EXHAUSTED"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.4.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.4.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.4.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.4.evidence.sessionsRequested","typeLabel":"integer"},"sessionsPlacedBefore":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.4.evidence.sessionsPlacedBefore","typeLabel":"integer"}},"required":["sessionsRequested","sessionsPlacedBefore"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.4.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.4","typeLabel":"object"},{"type":"object","description":"This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["CADENCE_RELAXED"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["cadence"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.cadenceRelaxation","typeLabel":"enum\u003cstring>"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays","typeLabel":"integer[]"},"actualDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.actualDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence.actualDays","typeLabel":"integer[]"}},"required":["cadenceRelaxation"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.5","typeLabel":"object"},{"type":"object","description":"These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_OUTSIDE_PREFERRED_TIMES"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["timeOfDay"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionIndexes":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes.items.[INDEX]","typeLabel":"integer"},"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes","typeLabel":"integer[]"},"localTimes":{"type":"array","items":{"type":"string","uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.localTimes.items.[INDEX]","typeLabel":"string"},"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence.localTimes","typeLabel":"string[]"}},"required":["sessionIndexes","localTimes"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.6","typeLabel":"object"},{"type":"object","description":"The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["FIRST_SESSION_LATE"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["startDate"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"firstSessionDate":{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.firstSessionDate","typeLabel":"string"},"windowStartDate":{"type":"string","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.windowStartDate","typeLabel":"string"},"dayOffset":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.dayOffset","typeLabel":"integer"},"earlierSupplyExisted":{"type":"boolean","description":"TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence.earlierSupplyExisted","typeLabel":"boolean"}},"required":["firstSessionDate","windowStartDate","dayOffset","earlierSupplyExisted"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.7","typeLabel":"object"},{"type":"object","description":"Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1.","required":["code","evidence"],"properties":{"code":{"type":"string","enum":["PACKAGE_UNDERFILLED"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.8.code","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.8.evidence.sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.8.evidence.sessionsFilled","typeLabel":"integer"}},"required":["sessionsRequested","sessionsFilled"],"isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.8.evidence","typeLabel":"object"}},"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX].oneOf.8","typeLabel":"object"}],"uniqueKey":"partial.oneOf.0.matchNotes.items.[INDEX]","typeLabel":"object"},"description":"Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one.","isRequired":true,"uniqueKey":"partial.oneOf.0.matchNotes","typeLabel":"object[]"},"matchScore":{"type":"number","minimum":0,"maximum":1,"description":"How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.","example":1,"isRequired":true,"uniqueKey":"partial.oneOf.0.matchScore","typeLabel":"number"},"position":{"type":"integer","minimum":0,"description":"0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.","example":0,"uniqueKey":"partial.oneOf.0.position","typeLabel":"integer"},"cadenceRrule":{"oneOf":[{"type":"string","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"partial.oneOf.0.cadenceRrule.oneOf.0","typeLabel":"string"},{"type":"null","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"partial.oneOf.0.cadenceRrule.oneOf.1","typeLabel":"null"}],"uniqueKey":"partial.oneOf.0.cadenceRrule","typeLabel":"string | null"},"matchesRequestedCadence":{"type":"boolean","description":"True when cadenceRrule is the rrule you asked for.","example":false,"uniqueKey":"partial.oneOf.0.matchesRequestedCadence","typeLabel":"boolean"},"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","uniqueKey":"partial.oneOf.0.cadenceRelaxation","typeLabel":"enum\u003cstring>"},"cadenceDistance":{"type":"integer","minimum":0,"description":"How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.","example":2,"uniqueKey":"partial.oneOf.0.cadenceDistance","typeLabel":"integer"},"cadenceSummary":{"type":"object","properties":{"requested":{"oneOf":[{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.requested.oneOf.0","typeLabel":"integer"},{"type":"null","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.requested.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.requested","typeLabel":"integer | null"},"peak":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).","example":4,"isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.peak","typeLabel":"integer"},"average":{"type":"number","minimum":0,"description":"Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.","example":2.25,"isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.average","typeLabel":"number"},"byWeek":{"type":"array","items":{"type":"object","properties":{"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) that starts this week.","example":"2026-09-14","isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.byWeek.items.[INDEX].weekStart","typeLabel":"string"},"sessions":{"type":"integer","minimum":0,"description":"Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.","example":0,"isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.byWeek.items.[INDEX].sessions","typeLabel":"integer"}},"required":["weekStart","sessions"],"uniqueKey":"partial.oneOf.0.cadenceSummary.byWeek.items.[INDEX]","typeLabel":"object"},"minItems":1,"description":"Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array.","isRequired":true,"uniqueKey":"partial.oneOf.0.cadenceSummary.byWeek","typeLabel":"object[]"}},"required":["requested","peak","average","byWeek"],"description":"How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like.","uniqueKey":"partial.oneOf.0.cadenceSummary","typeLabel":"object"},"advice":{"type":"object","properties":{"code":{"type":"string","enum":["LATER_START_IMPROVES_CADENCE"],"isRequired":true,"uniqueKey":"partial.oneOf.0.advice.code","typeLabel":"enum\u003cstring>"},"earliestSustainedWeek":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.","example":"2026-09-14","isRequired":true,"uniqueKey":"partial.oneOf.0.advice.earliestSustainedWeek","typeLabel":"string"}},"required":["code","earliestSustainedWeek"],"description":"An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built.","uniqueKey":"partial.oneOf.0.advice","typeLabel":"object"},"matchComponents":{"type":"object","properties":{"startDate":{"type":"number","minimum":0,"maximum":1,"description":"How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands.","uniqueKey":"partial.oneOf.0.matchComponents.startDate","typeLabel":"number"},"timeOfDay":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall at a preferred time of day.","uniqueKey":"partial.oneOf.0.matchComponents.timeOfDay","typeLabel":"number"},"daysOfWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall on a requested weekday.","uniqueKey":"partial.oneOf.0.matchComponents.daysOfWeek","typeLabel":"number"},"sessionsPerWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore.","uniqueKey":"partial.oneOf.0.matchComponents.sessionsPerWeek","typeLabel":"number"},"cadence":{"type":"number","minimum":0,"maximum":1,"description":"1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule.","uniqueKey":"partial.oneOf.0.matchComponents.cadence","typeLabel":"number"}},"description":"How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report.","uniqueKey":"partial.oneOf.0.matchComponents","typeLabel":"object"}},"required":["slateId","supplierId","completeness","sessionsRequested","sessionsFilled","startTimeConsistencyPercent","totalTravelTimeMins","slots","matchNotes","matchScore"],"isRequired":true,"uniqueKey":"partial.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"slateId":{"type":"string","description":"Pass this to POST .../package-bookings to book the whole plan.","example":"slate_01kx16ejsqffc9rbgdcc591w2p"},"supplierId":{"type":"string"},"completeness":{"type":"string","enum":["COMPLETE","PARTIAL"]},"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"How many sessions were requested (the package's creditCount)."},"sessionsFilled":{"type":"integer","minimum":0,"description":"How many of the requested sessions the plan could fill."},"startTimeConsistencyPercent":{"type":"number","minimum":0,"maximum":100},"totalTravelTimeMins":{"type":"number","minimum":0},"slots":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string","description":"Id of one session; pass a subset of these as slotIds to cherry-pick."},"sessionIndex":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"1-based index of this session within the slate."},"supplierId":{"type":"string"},"serviceId":{"type":"string"},"offeringId":{"type":"string"},"bookingStartUtc":{"type":"string","format":"date-time"},"bookingEndUtc":{"type":"string","format":"date-time"},"bookingTz":{"type":"string"},"locationType":{"type":"string","enum":["PHYSICAL","VIRTUAL","TRAVEL_ZONE"]},"locationId":{"oneOf":[{"type":"string"},{"type":"null"}]},"latitude":{"oneOf":[{"type":"number"},{"type":"null"}]},"longitude":{"oneOf":[{"type":"number"},{"type":"null"}]},"address":{"oneOf":[{"type":"object","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"]},{"type":"null","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"]}]},"travelTimeMins":{"oneOf":[{"type":"number","minimum":0},{"type":"null","minimum":0}]},"capacity":{"type":"integer","minimum":0,"exclusiveMinimum":true},"reservationStatus":{"type":"string","enum":["FREE","HELD","CONVERTED","RELEASED"]}},"required":["slotId","sessionIndex","supplierId","serviceId","offeringId","bookingStartUtc","bookingEndUtc","bookingTz","locationType","locationId","latitude","longitude","address","travelTimeMins","capacity","reservationStatus"]}},"position":{"type":"integer","minimum":0,"description":"0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.","example":0},"cadenceRrule":{"oneOf":[{"type":"string","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"},{"type":"null","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"}]},"matchesRequestedCadence":{"type":"boolean","description":"True when cadenceRrule is the rrule you asked for.","example":false},"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."},"cadenceDistance":{"type":"integer","minimum":0,"description":"How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.","example":2},"cadenceSummary":{"type":"object","properties":{"requested":{"oneOf":[{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4},{"type":"null","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4}]},"peak":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).","example":4},"average":{"type":"number","minimum":0,"description":"Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.","example":2.25},"byWeek":{"type":"array","items":{"type":"object","properties":{"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) that starts this week.","example":"2026-09-14"},"sessions":{"type":"integer","minimum":0,"description":"Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.","example":0}},"required":["weekStart","sessions"]},"minItems":1,"description":"Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."}},"required":["requested","peak","average","byWeek"],"description":"How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."},"matchNotes":{"type":"array","items":{"oneOf":[{"type":"object","description":"This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SUPPLIER_UNAVAILABLE_WEEK"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool","supplierWorkdays"]}}},{"type":"object","description":"Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_EXCLUDED_BY_FILTERS"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"filter":{"type":"string","enum":["daysOfWeek","excludeDates"]},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."},"excludedDates":{"type":"array","items":{"type":"string"}}},"required":["sessionsPlaced","sessionsTargeted","filter","supplierWorkdays"]}}},{"type":"object","description":"This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_SUPPLY_INSUFFICIENT"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool"]}}},{"type":"object","description":"This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_CAPPED"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week."},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target."},"cap":{"type":"string","enum":["maxSessionsPerWeek","minGapDays"]},"capValue":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["sessionsPlaced","sessionsTargeted","cap","capValue"]}}},{"type":"object","description":"This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_EXHAUSTED"]},"component":{"type":"string","enum":["sessionsPerWeek"]},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true},"sessionsPlacedBefore":{"type":"integer","minimum":0}},"required":["sessionsRequested","sessionsPlacedBefore"]}}},{"type":"object","description":"This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["CADENCE_RELAXED"]},"component":{"type":"string","enum":["cadence"]},"evidence":{"type":"object","properties":{"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."},"actualDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Weekdays as 0 = Sunday … 6 = Saturday."}},"required":["cadenceRelaxation"]}}},{"type":"object","description":"These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_OUTSIDE_PREFERRED_TIMES"]},"component":{"type":"string","enum":["timeOfDay"]},"evidence":{"type":"object","properties":{"sessionIndexes":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"localTimes":{"type":"array","items":{"type":"string"}}},"required":["sessionIndexes","localTimes"]}}},{"type":"object","description":"The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["FIRST_SESSION_LATE"]},"component":{"type":"string","enum":["startDate"]},"evidence":{"type":"object","properties":{"firstSessionDate":{"type":"string"},"windowStartDate":{"type":"string"},"dayOffset":{"type":"integer","minimum":0},"earlierSupplyExisted":{"type":"boolean","description":"TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."}},"required":["firstSessionDate","windowStartDate","dayOffset","earlierSupplyExisted"]}}},{"type":"object","description":"Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1.","required":["code","evidence"],"properties":{"code":{"type":"string","enum":["PACKAGE_UNDERFILLED"]},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true},"sessionsFilled":{"type":"integer","minimum":0}},"required":["sessionsRequested","sessionsFilled"]}}}]},"description":"Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."},"advice":{"type":"object","properties":{"code":{"type":"string","enum":["LATER_START_IMPROVES_CADENCE"]},"earliestSustainedWeek":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.","example":"2026-09-14"}},"required":["code","earliestSustainedWeek"],"description":"An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."},"matchScore":{"type":"number","minimum":0,"maximum":1,"description":"How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.","example":1},"matchComponents":{"type":"object","properties":{"startDate":{"type":"number","minimum":0,"maximum":1,"description":"How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."},"timeOfDay":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall at a preferred time of day."},"daysOfWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall on a requested weekday."},"sessionsPerWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."},"cadence":{"type":"number","minimum":0,"maximum":1,"description":"1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."}},"description":"How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."}},"required":["slateId","supplierId","completeness","sessionsRequested","sessionsFilled","startTimeConsistencyPercent","totalTravelTimeMins","slots","matchNotes","matchScore"],"isRequired":true,"uniqueKey":"partial.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"partial","typeLabel":"object | null"},"searchId":{"type":"string","description":"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","uniqueKey":"searchId","typeLabel":"string"},"cadenceAlternatives":{"type":"array","items":{"type":"object","properties":{"slateId":{"type":"string","description":"Pass this to POST .../package-bookings to book the whole plan.","example":"slate_01kx16ejsqffc9rbgdcc591w2p","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slateId","typeLabel":"string"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].supplierId","typeLabel":"string"},"completeness":{"type":"string","enum":["COMPLETE","PARTIAL"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].completeness","typeLabel":"enum\u003cstring>"},"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"How many sessions were requested (the package's creditCount).","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"description":"How many of the requested sessions the plan could fill.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].sessionsFilled","typeLabel":"integer"},"startTimeConsistencyPercent":{"type":"number","minimum":0,"maximum":100,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].startTimeConsistencyPercent","typeLabel":"number"},"totalTravelTimeMins":{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].totalTravelTimeMins","typeLabel":"number"},"slots":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string","description":"Id of one session; pass a subset of these as slotIds to cherry-pick.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].slotId","typeLabel":"string"},"sessionIndex":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"1-based index of this session within the slate.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].sessionIndex","typeLabel":"integer"},"supplierId":{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].supplierId","typeLabel":"string"},"serviceId":{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].serviceId","typeLabel":"string"},"offeringId":{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].offeringId","typeLabel":"string"},"bookingStartUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].bookingStartUtc","typeLabel":"string\u003cdate-time>"},"bookingEndUtc":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].bookingEndUtc","typeLabel":"string\u003cdate-time>"},"bookingTz":{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].bookingTz","typeLabel":"string"},"locationType":{"type":"string","enum":["PHYSICAL","VIRTUAL","TRAVEL_ZONE"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].locationType","typeLabel":"enum\u003cstring>"},"locationId":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].locationId.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].locationId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].locationId","typeLabel":"string | null"},"latitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].latitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].latitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].latitude","typeLabel":"number | null"},"longitude":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].longitude.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].longitude.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].longitude","typeLabel":"number | null"},"address":{"oneOf":[{"type":"object","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.addressOneLine","typeLabel":"string"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.streetNumber","typeLabel":"string"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.streetName","typeLabel":"string"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.city","typeLabel":"string"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.state","typeLabel":"string"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.country","typeLabel":"string"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.zipCode","typeLabel":"string"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.0","typeLabel":"string"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B","uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.unitNumber.oneOf.1","typeLabel":"null"}],"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0.unitNumber","typeLabel":"string | null"}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"addressOneLine":{"type":"string","minLength":1,"description":"The whole address on one line, as a person would write it.","example":"10 Main St, Toronto, ON M5V 1A1, Canada"},"streetNumber":{"type":"string","minLength":1,"description":"The street number.","example":"10"},"streetName":{"type":"string","minLength":1,"description":"The street name.","example":"Main St"},"city":{"type":"string","minLength":1,"description":"The city or town.","example":"Toronto"},"state":{"type":"string","minLength":1,"description":"The state, province or region; an ISO 3166-2 code when one matches.","example":"ON"},"country":{"type":"string","minLength":1,"description":"The country; ISO 3166-1 alpha-2, alpha-3 or the English name.","example":"CA"},"zipCode":{"type":"string","minLength":1,"description":"The postal or ZIP code, in any national format.","example":"M5V 1A1"},"unitNumber":{"oneOf":[{"type":"string","description":"The unit, suite or apartment, if any.","example":"4B"},{"type":"null","description":"The unit, suite or apartment, if any.","example":"4B"}]}},"required":["addressOneLine","streetNumber","streetName","city","state","country","zipCode"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].address","typeLabel":"object | null"},"travelTimeMins":{"oneOf":[{"type":"number","minimum":0,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].travelTimeMins.oneOf.0","typeLabel":"number"},{"type":"null","minimum":0,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].travelTimeMins.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].travelTimeMins","typeLabel":"number | null"},"capacity":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].capacity","typeLabel":"integer"},"reservationStatus":{"type":"string","enum":["FREE","HELD","CONVERTED","RELEASED"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX].reservationStatus","typeLabel":"enum\u003cstring>"}},"required":["slotId","sessionIndex","supplierId","serviceId","offeringId","bookingStartUtc","bookingEndUtc","bookingTz","locationType","locationId","latitude","longitude","address","travelTimeMins","capacity","reservationStatus"],"uniqueKey":"cadenceAlternatives.items.[INDEX].slots.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].slots","typeLabel":"object[]"},"matchNotes":{"type":"array","items":{"oneOf":[{"type":"object","description":"This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SUPPLIER_UNAVAILABLE_WEEK"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.openingsInPool","typeLabel":"integer"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence.supplierWorkdays","typeLabel":"integer[]"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool","supplierWorkdays"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.0","typeLabel":"object"},{"type":"object","description":"Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_EXCLUDED_BY_FILTERS"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.sessionsTargeted","typeLabel":"integer"},"filter":{"type":"string","enum":["daysOfWeek","excludeDates"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.filter","typeLabel":"enum\u003cstring>"},"supplierWorkdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.supplierWorkdays","typeLabel":"integer[]"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.requestedDays","typeLabel":"integer[]"},"excludedDates":{"type":"array","items":{"type":"string","uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates.items.[INDEX]","typeLabel":"string"},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence.excludedDates","typeLabel":"string[]"}},"required":["sessionsPlaced","sessionsTargeted","filter","supplierWorkdays"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.1","typeLabel":"object"},{"type":"object","description":"This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_SUPPLY_INSUFFICIENT"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence.sessionsTargeted","typeLabel":"integer"},"openingsInPool":{"type":"integer","minimum":0,"description":"Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.","example":2,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence.openingsInPool","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","openingsInPool"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.2","typeLabel":"object"},{"type":"object","description":"This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["WEEK_CAPPED"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsPlaced":{"type":"integer","minimum":0,"description":"Sessions this slate placed in this week.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.sessionsPlaced","typeLabel":"integer"},"sessionsTargeted":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Sessions you asked for in a week — your sessionsPerWeek target.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.sessionsTargeted","typeLabel":"integer"},"cap":{"type":"string","enum":["maxSessionsPerWeek","minGapDays"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.cap","typeLabel":"enum\u003cstring>"},"capValue":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence.capValue","typeLabel":"integer"}},"required":["sessionsPlaced","sessionsTargeted","cap","capValue"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.3","typeLabel":"object"},{"type":"object","description":"This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy.","required":["code","component","weekStart","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_EXHAUSTED"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["sessionsPerWeek"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.component","typeLabel":"enum\u003cstring>"},"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) starting the week this note is about.","example":"2026-09-14","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.weekStart","typeLabel":"string"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.evidence.sessionsRequested","typeLabel":"integer"},"sessionsPlacedBefore":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.evidence.sessionsPlacedBefore","typeLabel":"integer"}},"required":["sessionsRequested","sessionsPlacedBefore"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.4.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.4","typeLabel":"object"},{"type":"object","description":"This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["CADENCE_RELAXED"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["cadence"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.cadenceRelaxation","typeLabel":"enum\u003cstring>"},"requestedDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.requestedDays","typeLabel":"integer[]"},"actualDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.actualDays.items.[INDEX]","typeLabel":"integer"},"description":"Weekdays as 0 = Sunday … 6 = Saturday.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence.actualDays","typeLabel":"integer[]"}},"required":["cadenceRelaxation"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.5","typeLabel":"object"},{"type":"object","description":"These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["SESSIONS_OUTSIDE_PREFERRED_TIMES"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["timeOfDay"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionIndexes":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes.items.[INDEX]","typeLabel":"integer"},"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.sessionIndexes","typeLabel":"integer[]"},"localTimes":{"type":"array","items":{"type":"string","uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.localTimes.items.[INDEX]","typeLabel":"string"},"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence.localTimes","typeLabel":"string[]"}},"required":["sessionIndexes","localTimes"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.6","typeLabel":"object"},{"type":"object","description":"The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong.","required":["code","component","evidence"],"properties":{"code":{"type":"string","enum":["FIRST_SESSION_LATE"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.code","typeLabel":"enum\u003cstring>"},"component":{"type":"string","enum":["startDate"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.component","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"firstSessionDate":{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.firstSessionDate","typeLabel":"string"},"windowStartDate":{"type":"string","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.windowStartDate","typeLabel":"string"},"dayOffset":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.dayOffset","typeLabel":"integer"},"earlierSupplyExisted":{"type":"boolean","description":"TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence.earlierSupplyExisted","typeLabel":"boolean"}},"required":["firstSessionDate","windowStartDate","dayOffset","earlierSupplyExisted"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.7","typeLabel":"object"},{"type":"object","description":"Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1.","required":["code","evidence"],"properties":{"code":{"type":"string","enum":["PACKAGE_UNDERFILLED"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.code","typeLabel":"enum\u003cstring>"},"evidence":{"type":"object","properties":{"sessionsRequested":{"type":"integer","minimum":0,"exclusiveMinimum":true,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.evidence.sessionsRequested","typeLabel":"integer"},"sessionsFilled":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.evidence.sessionsFilled","typeLabel":"integer"}},"required":["sessionsRequested","sessionsFilled"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.8.evidence","typeLabel":"object"}},"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX].oneOf.8","typeLabel":"object"}],"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes.items.[INDEX]","typeLabel":"object"},"description":"Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchNotes","typeLabel":"object[]"},"matchScore":{"type":"number","minimum":0,"maximum":1,"description":"How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.","example":1,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchScore","typeLabel":"number"},"position":{"type":"integer","minimum":0,"description":"0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.","example":0,"uniqueKey":"cadenceAlternatives.items.[INDEX].position","typeLabel":"integer"},"cadenceRrule":{"oneOf":[{"type":"string","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceRrule.oneOf.0","typeLabel":"string"},{"type":"null","description":"The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.","example":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceRrule.oneOf.1","typeLabel":"null"}],"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceRrule","typeLabel":"string | null"},"matchesRequestedCadence":{"type":"boolean","description":"True when cadenceRrule is the rrule you asked for.","example":false,"uniqueKey":"cadenceAlternatives.items.[INDEX].matchesRequestedCadence","typeLabel":"boolean"},"cadenceRelaxation":{"type":"string","enum":["EXACT","INTERVAL_TIGHTENED","DAYS_ADDED","DAYS_SUBSTITUTED","ALL_WORKING_DAYS","DIRECT_FILL"],"description":"How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day.","uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceRelaxation","typeLabel":"enum\u003cstring>"},"cadenceDistance":{"type":"integer","minimum":0,"description":"How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.","example":2,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceDistance","typeLabel":"integer"},"cadenceSummary":{"type":"object","properties":{"requested":{"oneOf":[{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.requested.oneOf.0","typeLabel":"integer"},{"type":"null","minimum":0,"exclusiveMinimum":true,"description":"The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.","example":4,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.requested.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.requested","typeLabel":"integer | null"},"peak":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).","example":4,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.peak","typeLabel":"integer"},"average":{"type":"number","minimum":0,"description":"Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.","example":2.25,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.average","typeLabel":"number"},"byWeek":{"type":"array","items":{"type":"object","properties":{"weekStart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The Monday (YYYY-MM-DD, local) that starts this week.","example":"2026-09-14","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.byWeek.items.[INDEX].weekStart","typeLabel":"string"},"sessions":{"type":"integer","minimum":0,"description":"Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.","example":0,"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.byWeek.items.[INDEX].sessions","typeLabel":"integer"}},"required":["weekStart","sessions"],"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.byWeek.items.[INDEX]","typeLabel":"object"},"minItems":1,"description":"Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array.","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary.byWeek","typeLabel":"object[]"}},"required":["requested","peak","average","byWeek"],"description":"How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like.","uniqueKey":"cadenceAlternatives.items.[INDEX].cadenceSummary","typeLabel":"object"},"advice":{"type":"object","properties":{"code":{"type":"string","enum":["LATER_START_IMPROVES_CADENCE"],"isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].advice.code","typeLabel":"enum\u003cstring>"},"earliestSustainedWeek":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.","example":"2026-09-14","isRequired":true,"uniqueKey":"cadenceAlternatives.items.[INDEX].advice.earliestSustainedWeek","typeLabel":"string"}},"required":["code","earliestSustainedWeek"],"description":"An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built.","uniqueKey":"cadenceAlternatives.items.[INDEX].advice","typeLabel":"object"},"matchComponents":{"type":"object","properties":{"startDate":{"type":"number","minimum":0,"maximum":1,"description":"How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchComponents.startDate","typeLabel":"number"},"timeOfDay":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall at a preferred time of day.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchComponents.timeOfDay","typeLabel":"number"},"daysOfWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of this slate’s sessions that fall on a requested weekday.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchComponents.daysOfWeek","typeLabel":"number"},"sessionsPerWeek":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchComponents.sessionsPerWeek","typeLabel":"number"},"cadence":{"type":"number","minimum":0,"maximum":1,"description":"1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchComponents.cadence","typeLabel":"number"}},"description":"How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report.","uniqueKey":"cadenceAlternatives.items.[INDEX].matchComponents","typeLabel":"object"}},"required":["slateId","supplierId","completeness","sessionsRequested","sessionsFilled","startTimeConsistencyPercent","totalTravelTimeMins","slots","matchNotes","matchScore"],"uniqueKey":"cadenceAlternatives.items.[INDEX]","typeLabel":"object"},"default":[],"description":"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.","uniqueKey":"cadenceAlternatives","typeLabel":"object[]"},"requestedCadence":{"oneOf":[{"type":"string","description":"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","uniqueKey":"requestedCadence.oneOf.0","typeLabel":"string"},{"type":"null","description":"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","uniqueKey":"requestedCadence.oneOf.1","typeLabel":"null"}],"uniqueKey":"requestedCadence","typeLabel":"string | null"}},"required":["status","reason","suggestionRequestId","resolvableUntil","primarySlate","alternates","partial"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"status":"OK","reason":"\u003cstring>","suggestionRequestId":"\u003cstring>","resolvableUntil":"2023-11-07T05:31:56Z","primarySlate":{"slateId":"slate_01kx16ejsqffc9rbgdcc591w2p","supplierId":"\u003cstring>","completeness":"COMPLETE","sessionsRequested":1,"sessionsFilled":1,"startTimeConsistencyPercent":50,"totalTravelTimeMins":1,"slots":[{"slotId":"\u003cstring>","sessionIndex":1,"supplierId":"\u003cstring>","serviceId":"\u003cstring>","offeringId":"\u003cstring>","bookingStartUtc":"2023-11-07T05:31:56Z","bookingEndUtc":"2023-11-07T05:31:56Z","bookingTz":"\u003cstring>","locationType":"PHYSICAL","locationId":"\u003cstring>","latitude":123,"longitude":123,"address":{"addressOneLine":"10 Main St, Toronto, ON M5V 1A1, Canada","streetNumber":"10","streetName":"Main St","city":"Toronto","state":"ON","country":"CA","zipCode":"M5V 1A1","unitNumber":"4B"},"travelTimeMins":1,"capacity":1,"reservationStatus":"FREE"}],"matchNotes":[{"code":"SUPPLIER_UNAVAILABLE_WEEK","component":"sessionsPerWeek","weekStart":"2026-09-14","evidence":{"sessionsPlaced":1,"sessionsTargeted":1,"openingsInPool":2,"supplierWorkdays":[3]}}],"matchScore":1,"position":0,"cadenceRrule":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","matchesRequestedCadence":false,"cadenceRelaxation":"EXACT","cadenceDistance":2,"cadenceSummary":{"requested":4,"peak":4,"average":2.25,"byWeek":[{"weekStart":"2026-09-14","sessions":0}]},"advice":{"code":"LATER_START_IMPROVES_CADENCE","earliestSustainedWeek":"2026-09-14"},"matchComponents":{"startDate":0.5,"timeOfDay":0.5,"daysOfWeek":0.5,"sessionsPerWeek":0.5,"cadence":0.5}},"alternates":[{"slateId":"slate_01kx16ejsqffc9rbgdcc591w2p","supplierId":"\u003cstring>","completeness":"COMPLETE","sessionsRequested":1,"sessionsFilled":1,"startTimeConsistencyPercent":50,"totalTravelTimeMins":1,"slots":[{"slotId":"\u003cstring>","sessionIndex":1,"supplierId":"\u003cstring>","serviceId":"\u003cstring>","offeringId":"\u003cstring>","bookingStartUtc":"2023-11-07T05:31:56Z","bookingEndUtc":"2023-11-07T05:31:56Z","bookingTz":"\u003cstring>","locationType":"PHYSICAL","locationId":"\u003cstring>","latitude":123,"longitude":123,"address":{"addressOneLine":"10 Main St, Toronto, ON M5V 1A1, Canada","streetNumber":"10","streetName":"Main St","city":"Toronto","state":"ON","country":"CA","zipCode":"M5V 1A1","unitNumber":"4B"},"travelTimeMins":1,"capacity":1,"reservationStatus":"FREE"}],"matchNotes":[{"code":"SUPPLIER_UNAVAILABLE_WEEK","component":"sessionsPerWeek","weekStart":"2026-09-14","evidence":{"sessionsPlaced":1,"sessionsTargeted":1,"openingsInPool":2,"supplierWorkdays":[3]}}],"matchScore":1,"position":0,"cadenceRrule":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","matchesRequestedCadence":false,"cadenceRelaxation":"EXACT","cadenceDistance":2,"cadenceSummary":{"requested":4,"peak":4,"average":2.25,"byWeek":[{"weekStart":"2026-09-14","sessions":0}]},"advice":{"code":"LATER_START_IMPROVES_CADENCE","earliestSustainedWeek":"2026-09-14"},"matchComponents":{"startDate":0.5,"timeOfDay":0.5,"daysOfWeek":0.5,"sessionsPerWeek":0.5,"cadence":0.5}}],"partial":{"slateId":"slate_01kx16ejsqffc9rbgdcc591w2p","supplierId":"\u003cstring>","completeness":"COMPLETE","sessionsRequested":1,"sessionsFilled":1,"startTimeConsistencyPercent":50,"totalTravelTimeMins":1,"slots":[{"slotId":"\u003cstring>","sessionIndex":1,"supplierId":"\u003cstring>","serviceId":"\u003cstring>","offeringId":"\u003cstring>","bookingStartUtc":"2023-11-07T05:31:56Z","bookingEndUtc":"2023-11-07T05:31:56Z","bookingTz":"\u003cstring>","locationType":"PHYSICAL","locationId":"\u003cstring>","latitude":123,"longitude":123,"address":{"addressOneLine":"10 Main St, Toronto, ON M5V 1A1, Canada","streetNumber":"10","streetName":"Main St","city":"Toronto","state":"ON","country":"CA","zipCode":"M5V 1A1","unitNumber":"4B"},"travelTimeMins":1,"capacity":1,"reservationStatus":"FREE"}],"matchNotes":[{"code":"SUPPLIER_UNAVAILABLE_WEEK","component":"sessionsPerWeek","weekStart":"2026-09-14","evidence":{"sessionsPlaced":1,"sessionsTargeted":1,"openingsInPool":2,"supplierWorkdays":[3]}}],"matchScore":1,"position":0,"cadenceRrule":"FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8","matchesRequestedCadence":false,"cadenceRelaxation":"EXACT","cadenceDistance":2,"cadenceSummary":{"requested":4,"peak":4,"average":2.25,"byWeek":[{"weekStart":"2026-09-14","sessions":0}]},"advice":{"code":"LATER_START_IMPROVES_CADENCE","earliestSustainedWeek":"2026-09-14"},"matchComponents":{"startDate":0.5,"timeOfDay":0.5,"daysOfWeek":0.5,"sessionsPerWeek":0.5,"cadence":0.5}},"searchId":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","cadenceAlternatives":[],"requestedCadence":"FREQ=WEEKLY;BYDAY=FR;COUNT=8"}}},"exampleType":"generated"}},"exampleType":"generated"},"13cd0bde-9c3c-4b85-81e8-18d15a71565d":{"description":"Validation error (code: BAD_REQUEST), or a credit that cannot be planned (code: INVALID_ORDER_REFERENCE | NOT_A_PACKAGE_ITEM)","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"7765dac0-4c61-43ba-9c72-fddd009a80f9":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"75a4de57-b213-43d5-a074-7bf52226c854":{"description":"API key cannot access this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"a5e2d0a3-57eb-4b0f-a00f-739baca4edab":{"description":"The package, order or order item was not found (code: NOT_FOUND)","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"937d0734-eb94-4c90-a9f0-1b0841a6c8f9":{"description":"The credit has no sessions left to plan, has expired, or is on a cancelled order (code: ORDER_ITEM_QUANTITY_UNAVAILABLE | PACKAGE_EXPIRED | ORDER_CANCELLED)","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"527f8efd-f07a-4a16-be5a-b4bf8774058c":{"description":"No complete or bookable slate — no primarySlate, no partial, and no cadenceAlternatives (code: NO_COMPLETE_SLATE | NO_AVAILABILITY)","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"db6d1cf6-4a08-4a4c-92da-023445e576e6":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"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`.","scopes":[],"schemeName":"ApiKeyAuth"}}},"servers":{"7f0c0cfd-7cba-4616-861f-ca7611ae4010":{"url":"https://apiv2.gomarketbox.com","description":"MarketBox Open API"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"x-api-key","description":"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`.","scopes":[],"schemeName":"ApiKeyAuth"},"schema":{"title":"x-api-key","type":"string","description":"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`.","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyAuth","name":"x-api-key"}],"title":"ApiKeyAuth"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"marketboxinc","siteName":"MarketBox API","title":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions - MarketBox API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-19T15:10:27.419Z","originalFileLocation":"api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Builds one or more \u0026quot;slates\u0026quot; — complete N-session plans for a package — from a single supplier\u0026#x27;s availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client\u0026#x27;s credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit\u0026#x27;s expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client\u0026#x27;s order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package\u0026#x27;s creditCount, or the credit\u0026#x27;s remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable. The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422. The response carries a searchId (also the X-MB-Search-Id header, and the persisted suggestion request\u0026#x27;s correlation id) and each slate its 0-based position across the whole response. Keep searchId for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: X-MB-Session-Key (an opaque key you choose, up to 64 characters) and X-MB-Client-Kind (browser, server, monitor or loadtest).\">\u003cmeta data-mint-head name=\"application-name\" content=\"MarketBox API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Build a single-supplier N-session package slate (policy-driven), persisting suggestions - MarketBox API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Builds one or more \u0026quot;slates\u0026quot; — complete N-session plans for a package — from a single supplier\u0026#x27;s availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client\u0026#x27;s credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit\u0026#x27;s expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client\u0026#x27;s order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package\u0026#x27;s creditCount, or the credit\u0026#x27;s remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable. The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422. The response carries a searchId (also the X-MB-Search-Id header, and the persisted suggestion request\u0026#x27;s correlation id) and each slate its 0-based position across the whole response. Keep searchId for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: X-MB-Session-Key (an opaque key you choose, up to 64 characters) and X-MB-Client-Kind (browser, server, monitor or loadtest).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"MarketBox API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://marketboxinc.mintlify.site/_mintlify/api/og/v2?division=Availability\u0026amp;title=Build+a+single-supplier+N-session+package+slate+%28policy-driven%29%2C+persisting+suggestions\u0026amp;description=Builds+one+or+more+%22slates%22+%E2%80%94+complete+N-session+plans+for+a+package+%E2%80%94+from+a+single+supplier%27s+availability.+Name+what+to+plan+in+ONE+of+two+ways%3A+packageId+%28s\u0026amp;theme=3a79fb7765978cda15c7035f\u0026amp;signature=5848faa286a24c30e3276fad9785fe153239dc7b6a63cf6fa1ace848df29aadc\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Build a single-supplier N-session package slate (policy-driven), persisting suggestions - MarketBox API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Builds one or more \u0026quot;slates\u0026quot; — complete N-session plans for a package — from a single supplier\u0026#x27;s availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client\u0026#x27;s credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit\u0026#x27;s expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client\u0026#x27;s order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package\u0026#x27;s creditCount, or the credit\u0026#x27;s remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable. The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422. The response carries a searchId (also the X-MB-Search-Id header, and the persisted suggestion request\u0026#x27;s correlation id) and each slate its 0-based position across the whole response. Keep searchId for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: X-MB-Session-Key (an opaque key you choose, up to 64 characters) and X-MB-Client-Kind (browser, server, monitor or loadtest).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://marketboxinc.mintlify.site/_mintlify/api/og/v2?division=Availability\u0026amp;title=Build+a+single-supplier+N-session+package+slate+%28policy-driven%29%2C+persisting+suggestions\u0026amp;description=Builds+one+or+more+%22slates%22+%E2%80%94+complete+N-session+plans+for+a+package+%E2%80%94+from+a+single+supplier%27s+availability.+Name+what+to+plan+in+ONE+of+two+ways%3A+packageId+%28s\u0026amp;theme=3a79fb7765978cda15c7035f\u0026amp;signature=5848faa286a24c30e3276fad9785fe153239dc7b6a63cf6fa1ace848df29aadc\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"MarketBox API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0087EE\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.gomarketbox.com/#organization\",\"name\":\"MarketBox API\",\"url\":\"https://docs.gomarketbox.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/marketboxinc/ajdEqdrEaJkvfx4T/logo/light.svg?fit=max\u0026auto=format\u0026n=ajdEqdrEaJkvfx4T\u0026q=85\u0026s=655948ee6454a1e06bfe0dffda47c7cc\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.gomarketbox.com#website\",\"name\":\"MarketBox API\",\"url\":\"https://docs.gomarketbox.com\",\"publisher\":{\"@id\":\"https://docs.gomarketbox.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions#webpage\",\"url\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions\",\"name\":\"Build a single-supplier N-session package slate (policy-driven), persisting suggestions\",\"description\":\"Builds one or more \\\"slates\\\" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit's expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client's order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package's creditCount, or the credit's remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable. The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422. The response carries a searchId (also the X-MB-Search-Id header, and the persisted suggestion request's correlation id) and each slate its 0-based position across the whole response. Keep searchId for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: X-MB-Session-Key (an opaque key you choose, up to 64 characters) and X-MB-Client-Kind (browser, server, monitor or loadtest).\",\"dateModified\":\"2026-11-19T15:10:27.419Z\",\"isPartOf\":{\"@id\":\"https://docs.gomarketbox.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.gomarketbox.com/api-reference/events/report-site-events-straight-from-the-browser-publishable-key-no-response-body\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Availability\",\"item\":\"https://docs.gomarketbox.com/api-reference/availability/find-suppliers-+-suggestedopen-slots-for-a-service-location-and-window\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Build a single-supplier N-session package slate (policy-driven), persisting suggestions\",\"item\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions#apireference\",\"headline\":\"Build a single-supplier N-session package slate (policy-driven), persisting suggestions\",\"name\":\"Build a single-supplier N-session package slate (policy-driven), persisting suggestions\",\"description\":\"Builds one or more \\\"slates\\\" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit's expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client's order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package's creditCount, or the credit's remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable. The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422. The response carries a searchId (also the X-MB-Search-Id header, and the persisted suggestion request's correlation id) and each slate its 0-based position across the whole response. Keep searchId for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: X-MB-Session-Key (an opaque key you choose, up to 64 characters) and X-MB-Client-Kind (browser, server, monitor or loadtest).\",\"url\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions\",\"mainEntityOfPage\":{\"@id\":\"https://docs.gomarketbox.com/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions#webpage\"},\"dateModified\":\"2026-11-19T15:10:27.419Z\",\"publisher\":{\"@id\":\"https://docs.gomarketbox.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.gomarketbox.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"MarketBox API\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"MarketBox API\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions.md","siteName":"MarketBox API","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Overview","pages":[{"title":"API reference","href":"/api-reference/introduction"}]},{"group":"Endpoints","pages":[{"group":"Events","pages":[{"title":"Report site events straight from the browser (publishable key, no response body)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/events/beacon","href":"/api-reference/events/report-site-events-straight-from-the-browser-publishable-key-no-response-body"},{"title":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/events","href":"/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views"}]},{"group":"Supplier plane","pages":[{"title":"Whether the signed-in person may use the supplier plane, and why not","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/access","href":"/api-reference/supplier-plane/whether-the-signed-in-person-may-use-the-supplier-plane-and-why-not"},{"title":"List the signed-in supplier’s bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/bookings","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-bookings"},{"title":"One of the signed-in supplier’s bookings, with services and participants","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}","href":"/api-reference/supplier-plane/one-of-the-signed-in-supplier’s-bookings-with-services-and-participants"},{"title":"Move one of the signed-in supplier’s bookings to another time","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}","href":"/api-reference/supplier-plane/move-one-of-the-signed-in-supplier’s-bookings-to-another-time"},{"title":"The signed-in supplier’s own attendance report on one of their bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/reports","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-own-attendance-report-on-one-of-their-bookings"},{"title":"File the signed-in supplier’s attendance report on one of their bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/reports","href":"/api-reference/supplier-plane/file-the-signed-in-supplier’s-attendance-report-on-one-of-their-bookings"},{"title":"Cancel one of the signed-in supplier’s bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/cancel","href":"/api-reference/supplier-plane/cancel-one-of-the-signed-in-supplier’s-bookings"},{"title":"List the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/schedules","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-schedules"},{"title":"Create a schedule for the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/schedules","href":"/api-reference/supplier-plane/create-a-schedule-for-the-signed-in-supplier"},{"title":"Get one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}","href":"/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-schedules"},{"title":"Delete one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}","href":"/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-schedules"},{"title":"Update one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}","href":"/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-schedules"},{"title":"Clone one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}/clone","href":"/api-reference/supplier-plane/clone-one-of-the-signed-in-supplier’s-schedules"},{"title":"Move the signed-in supplier’s schedules and blocked times to their profile zone","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/availability-timezone/apply-profile","href":"/api-reference/supplier-plane/move-the-signed-in-supplier’s-schedules-and-blocked-times-to-their-profile-zone"},{"title":"List the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/blocked-times","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-blocked-times"},{"title":"Create a blocked time for the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/blocked-times","href":"/api-reference/supplier-plane/create-a-blocked-time-for-the-signed-in-supplier"},{"title":"Get one of the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}","href":"/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-blocked-times"},{"title":"Delete one of the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}","href":"/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-blocked-times"},{"title":"Update one of the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}","href":"/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-blocked-times"},{"title":"The signed-in supplier’s Week \u0026 demand view","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/demand","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-week-\u0026-demand-view"},{"title":"Dismiss one of the signed-in supplier’s demand suggestions for 90 days","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/demand/suggestions/{key}/dismiss","href":"/api-reference/supplier-plane/dismiss-one-of-the-signed-in-supplier’s-demand-suggestions-for-90-days"},{"title":"Undo a dismissal: the suggestion shows again when the data still supports it","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/demand/suggestions/{key}/dismiss","href":"/api-reference/supplier-plane/undo-a-dismissal:-the-suggestion-shows-again-when-the-data-still-supports-it"},{"title":"The signed-in supplier’s Search insights","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/search-insights","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-search-insights"},{"title":"The signed-in supplier’s own profile","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-own-profile"},{"title":"Update the signed-in supplier’s own profile","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me","href":"/api-reference/supplier-plane/update-the-signed-in-supplier’s-own-profile"},{"title":"Get a presigned URL to upload the signed-in supplier’s photo","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/avatar/upload-url","href":"/api-reference/supplier-plane/get-a-presigned-url-to-upload-the-signed-in-supplier’s-photo"},{"title":"Attach the uploaded photo to the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/suppliers/me/avatar","href":"/api-reference/supplier-plane/attach-the-uploaded-photo-to-the-signed-in-supplier"},{"title":"Remove the signed-in supplier’s photo","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/avatar","href":"/api-reference/supplier-plane/remove-the-signed-in-supplier’s-photo"},{"title":"List the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/travel-zones","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-travel-zones"},{"title":"Create a travel zone for the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/travel-zones","href":"/api-reference/supplier-plane/create-a-travel-zone-for-the-signed-in-supplier"},{"title":"Get one of the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}","href":"/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-travel-zones"},{"title":"Delete one of the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}","href":"/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-travel-zones"},{"title":"Update one of the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}","href":"/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-travel-zones"},{"title":"List the venues the signed-in supplier may be scheduled at","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/locations","href":"/api-reference/supplier-plane/list-the-venues-the-signed-in-supplier-may-be-scheduled-at"},{"title":"List the signed-in supplier’s alerts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/alerts","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-alerts"},{"title":"The signed-in supplier’s unread count and open conditions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/alerts/summary","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-unread-count-and-open-conditions"},{"title":"Mark all of the signed-in supplier’s alerts read","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/alerts/read-all","href":"/api-reference/supplier-plane/mark-all-of-the-signed-in-supplier’s-alerts-read"},{"title":"Mark one of the signed-in supplier’s alerts read","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/alerts/{alertId}/read","href":"/api-reference/supplier-plane/mark-one-of-the-signed-in-supplier’s-alerts-read"}]},{"group":"Bookings","pages":[{"title":"List bookings for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings","href":"/api-reference/bookings/list-bookings-for-a-project"},{"title":"Create a new booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings","href":"/api-reference/bookings/create-a-new-booking"},{"title":"Get a booking by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}","href":"/api-reference/bookings/get-a-booking-by-id"},{"title":"Soft-delete a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/bookings/{bookingId}","href":"/api-reference/bookings/soft-delete-a-booking"},{"title":"Reschedule or update a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/bookings/{bookingId}","href":"/api-reference/bookings/reschedule-or-update-a-booking"},{"title":"Get a booking with its services, participants, notes, reports and party names","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/aggregate","href":"/api-reference/bookings/get-a-booking-with-its-services-participants-notes-reports-and-party-names"},{"title":"Change a booking status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/status","href":"/api-reference/bookings/change-a-booking-status"},{"title":"List bookings for a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/{supplierId}/bookings","href":"/api-reference/bookings/list-bookings-for-a-supplier"},{"title":"List bookings for a client","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/bookings","href":"/api-reference/bookings/list-bookings-for-a-client"},{"title":"List participants on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/participants","href":"/api-reference/bookings/list-participants-on-a-booking"},{"title":"Register a participant on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/participants","href":"/api-reference/bookings/register-a-participant-on-a-booking"},{"title":"Get a single booking participant","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}","href":"/api-reference/bookings/get-a-single-booking-participant"},{"title":"Cancel a booking participant","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}","href":"/api-reference/bookings/cancel-a-booking-participant"},{"title":"Check in a participant","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}/check-in","href":"/api-reference/bookings/check-in-a-participant"},{"title":"List booking notes","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/notes","href":"/api-reference/bookings/list-booking-notes"},{"title":"Create a booking note","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/notes","href":"/api-reference/bookings/create-a-booking-note"},{"title":"Delete a booking note","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}","href":"/api-reference/bookings/delete-a-booking-note"},{"title":"Update a booking note","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}","href":"/api-reference/bookings/update-a-booking-note"},{"title":"List the reports filed on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/reports","href":"/api-reference/bookings/list-the-reports-filed-on-a-booking"},{"title":"File one side's report on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/reports","href":"/api-reference/bookings/file-one-sides-report-on-a-booking"}]},{"group":"Reviews","pages":[{"title":"List every review linked to a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/reviews","href":"/api-reference/reviews/list-every-review-linked-to-a-booking"},{"title":"Review a booking, in either direction","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/reviews","href":"/api-reference/reviews/review-a-booking-in-either-direction"},{"title":"List reviews for a project (newest first); filter by supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/reviews","href":"/api-reference/reviews/list-reviews-for-a-project-newest-first;-filter-by-supplier"},{"title":"Create a supplier review (1–5 star rating with optional comment)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/reviews","href":"/api-reference/reviews/create-a-supplier-review-1–5-star-rating-with-optional-comment"},{"title":"List the reviews written about a client","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/reviews","href":"/api-reference/reviews/list-the-reviews-written-about-a-client"},{"title":"Get a client's average rating and review count","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/review-summary","href":"/api-reference/reviews/get-a-clients-average-rating-and-review-count"},{"title":"Get a supplier's average rating and review count","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/{supplierId}/review-summary","href":"/api-reference/reviews/get-a-suppliers-average-rating-and-review-count"}]},{"group":"Orders","pages":[{"title":"List orders by status, by payment method, or every order in a date range","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders","href":"/api-reference/orders/list-orders-by-status-by-payment-method-or-every-order-in-a-date-range"},{"title":"Create a new order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders","href":"/api-reference/orders/create-a-new-order"},{"title":"Get an order by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders/{orderId}","href":"/api-reference/orders/get-an-order-by-id"},{"title":"Soft-delete an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/orders/{orderId}","href":"/api-reference/orders/soft-delete-an-order"},{"title":"Update an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/orders/{orderId}","href":"/api-reference/orders/update-an-order"},{"title":"Get an order with its items","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders/{orderId}/aggregate","href":"/api-reference/orders/get-an-order-with-its-items"},{"title":"List orders for a client","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/orders","href":"/api-reference/orders/list-orders-for-a-client"},{"title":"Change order status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/status","href":"/api-reference/orders/change-order-status"},{"title":"Add an item to an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/items","href":"/api-reference/orders/add-an-item-to-an-order"},{"title":"Remove an order item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}","href":"/api-reference/orders/remove-an-order-item"},{"title":"Update an order item quantity","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}","href":"/api-reference/orders/update-an-order-item-quantity"},{"title":"List the bookings created for a PACKAGE order item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders/{orderId}/package-bookings","href":"/api-reference/orders/list-the-bookings-created-for-a-package-order-item"},{"title":"Create N package sessions atomically (or best-effort) from one PACKAGE order item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/package-bookings","href":"/api-reference/orders/create-n-package-sessions-atomically-or-best-effort-from-one-package-order-item"}]},{"group":"Suppliers","pages":[{"title":"List suppliers for a project, enriched with services and skills; filter by service/skill/region/point","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers","href":"/api-reference/suppliers/list-suppliers-for-a-project-enriched-with-services-and-skills;-filter-by-serviceskillregionpoint"},{"title":"Create a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers","href":"/api-reference/suppliers/create-a-supplier"},{"title":"One supplier in full: profile, services, skills, locations, rating and working hours","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/{supplierId}","href":"/api-reference/suppliers/one-supplier-in-full:-profile-services-skills-locations-rating-and-working-hours"},{"title":"Update a supplier; sync its service/skill mappings when arrays are supplied","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/suppliers/{supplierId}","href":"/api-reference/suppliers/update-a-supplier;-sync-its-serviceskill-mappings-when-arrays-are-supplied"},{"title":"Soft-delete a supplier (cascade-removes its mappings and avatar)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}","href":"/api-reference/suppliers/soft-delete-a-supplier-cascade-removes-its-mappings-and-avatar"},{"title":"Add a service to a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}","href":"/api-reference/suppliers/add-a-service-to-a-supplier"},{"title":"Remove a service from a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}","href":"/api-reference/suppliers/remove-a-service-from-a-supplier"},{"title":"Add a skill to a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}","href":"/api-reference/suppliers/add-a-skill-to-a-supplier"},{"title":"Remove a skill from a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}","href":"/api-reference/suppliers/remove-a-skill-from-a-supplier"},{"title":"Get a presigned URL to upload a supplier avatar","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/{supplierId}/avatar/upload-url","href":"/api-reference/suppliers/get-a-presigned-url-to-upload-a-supplier-avatar"},{"title":"Confirm an uploaded avatar and attach it to the supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/suppliers/{supplierId}/avatar","href":"/api-reference/suppliers/confirm-an-uploaded-avatar-and-attach-it-to-the-supplier"},{"title":"Remove a supplier's avatar","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}/avatar","href":"/api-reference/suppliers/remove-a-suppliers-avatar"}]},{"group":"Availability","pages":[{"title":"Find suppliers + suggested/open slots for a service, location and window","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/search","href":"/api-reference/availability/find-suppliers-+-suggestedopen-slots-for-a-service-location-and-window"},{"title":"Generate clustered time slots from suppliers + engine config","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/time-slots","href":"/api-reference/availability/generate-clustered-time-slots-from-suppliers-+-engine-config"},{"title":"Supplier-centric availability: paginated suppliers, each with open slots grouped by day","description":"Returns availability grouped by supplier — a paginated list of suppliers, each with its full profile (same shape as GET /suppliers) and its open slots bucketed by local day. Use this to render a wall of supplier cards with bookable times, instead of the flat, slot-centric arrays /availability/search returns. Provide serviceId + offeringId and either locationId or both lat and lng. Returns regular-interval open slots only — no clustered/travel-optimized suggestions and no recurring patterns (use /availability/search for those). Suppliers that match the service and location but have no availability in the window are still returned, with days: []. Paginate with limit (max 50) + the opaque cursor; nextCursor is null on the last page. Each slot carries a UTC anchor (startUtc/endUtc) plus *Local strings rendered in the request timezone.\n\nEvery page carries the same `searchId` (also the `X-MB-Search-Id` header; the cursor keeps it) and each supplier its 0-based `position`, continuous across pages. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/suppliers","href":"/api-reference/availability/supplier-centric-availability:-paginated-suppliers-each-with-open-slots-grouped-by-day"},{"title":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/package-slate","href":"/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions"},{"title":"List a service's packages, each with a ready-to-book slate","description":"Returns every ACTIVE package of a service, each with a complete N-session plan built from a supplier's real availability. The response entry carries a slateId that can be booked directly via POST /orders/{orderId}/package-bookings. Cadence defaults to FREQ=WEEKLY;COUNT={creditCount}, derived per package. Packages that cannot be planned come back with status NO_COMPLETE_SLATE or NO_AVAILABILITY and a reason — they do not fail the request.\n\nThe rrule is the PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) and it applies to every package in the response. An entry that has no complete plan on the requested days then comes back with status ALTERNATIVE_CADENCE and a non-empty cadenceAlternatives: complete slates at a denser, supplier-feasible cadence, sorted closest-first by cadenceDistance. Read the outcome from each entry's status: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome, and ALTERNATIVE_CADENCE is a success — every cadenceAlternatives entry carries a slateId that is bookable in exactly the same way as primarySlate. A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE and cadenceAlternatives comes back empty.\n\nThe response carries a `searchId` (also the `X-MB-Search-Id` header, and the correlation id of every suggestion request this call persisted) and each slate its 0-based `position` within its package. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/package-options","href":"/api-reference/availability/list-a-services-packages-each-with-a-ready-to-book-slate"}]},{"group":"Suggestions","pages":[{"title":"Reschedule a suggested slot to a new time (server-validated), refreshing its slate","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule","href":"/api-reference/suggestions/reschedule-a-suggested-slot-to-a-new-time-server-validated-refreshing-its-slate"}]},{"group":"Holds","pages":[{"title":"Hold supplier time during checkout — a single session, or a whole package slate","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/holds","href":"/api-reference/holds/hold-supplier-time-during-checkout-—-a-single-session-or-a-whole-package-slate"},{"title":"Read a hold — its status, its heldUntil, and the supplier time it claims","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/holds/{reservationId}","href":"/api-reference/holds/read-a-hold-—-its-status-its-helduntil-and-the-supplier-time-it-claims"},{"title":"Release a hold (HELD → RELEASED) — idempotent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/holds/{reservationId}/release","href":"/api-reference/holds/release-a-hold-held-→-released-—-idempotent"},{"title":"Convert a hold into confirmed bookings (the idempotent purchase hook)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/holds/{reservationId}/convert","href":"/api-reference/holds/convert-a-hold-into-confirmed-bookings-the-idempotent-purchase-hook"}]},{"group":"Clients","pages":[{"title":"Onboard the authenticated client to a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/clients/me","href":"/api-reference/clients/onboard-the-authenticated-client-to-a-project"},{"title":"Update the authenticated client's contact details","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/clients/me","href":"/api-reference/clients/update-the-authenticated-clients-contact-details"},{"title":"Get the authenticated client's package credits","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/me/credits","href":"/api-reference/clients/get-the-authenticated-clients-package-credits"},{"title":"Book sessions from the authenticated client's own package credit","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/clients/me/orders/{orderId}/package-bookings","href":"/api-reference/clients/book-sessions-from-the-authenticated-clients-own-package-credit"},{"title":"Add a service address to the caller's client profile","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/clients/me/addresses","href":"/api-reference/clients/add-a-service-address-to-the-callers-client-profile"},{"title":"Remove one of the caller's addresses","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/clients/me/addresses/{addressId}","href":"/api-reference/clients/remove-one-of-the-callers-addresses"},{"title":"Update one of the caller's addresses","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/clients/me/addresses/{addressId}","href":"/api-reference/clients/update-one-of-the-callers-addresses"},{"title":"Set the caller's default address","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/clients/me/addresses/{addressId}/default","href":"/api-reference/clients/set-the-callers-default-address"}]},{"group":"Services","pages":[{"title":"List services for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services","href":"/api-reference/services/list-services-for-a-project"},{"title":"Create a new service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services","href":"/api-reference/services/create-a-new-service"},{"title":"Get a service by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}","href":"/api-reference/services/get-a-service-by-id"},{"title":"Update a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/services/{serviceId}","href":"/api-reference/services/update-a-service"},{"title":"Soft delete a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/services/{serviceId}","href":"/api-reference/services/soft-delete-a-service"},{"title":"Change service status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/status","href":"/api-reference/services/change-service-status"}]},{"group":"ServiceBusinessModels","pages":[{"title":"List business models for a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/business-models","href":"/api-reference/servicebusinessmodels/list-business-models-for-a-service"},{"title":"Add a business model to a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/business-models","href":"/api-reference/servicebusinessmodels/add-a-business-model-to-a-service"},{"title":"Update a business model","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}","href":"/api-reference/servicebusinessmodels/update-a-business-model"},{"title":"Toggle business model active status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}/status","href":"/api-reference/servicebusinessmodels/toggle-business-model-active-status"}]},{"group":"ServiceOfferings","pages":[{"title":"List offerings for a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/offerings","href":"/api-reference/serviceofferings/list-offerings-for-a-service"},{"title":"Add an offering to a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings","href":"/api-reference/serviceofferings/add-an-offering-to-a-service"},{"title":"Get an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}","href":"/api-reference/serviceofferings/get-an-offering"},{"title":"Update an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}","href":"/api-reference/serviceofferings/update-an-offering"},{"title":"Soft delete an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}","href":"/api-reference/serviceofferings/soft-delete-an-offering"},{"title":"Change offering status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/status","href":"/api-reference/serviceofferings/change-offering-status"}]},{"group":"ServicePackages","pages":[{"title":"List packages for an offering (storefront)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages","href":"/api-reference/servicepackages/list-packages-for-an-offering-storefront"},{"title":"Create a sellable package (bundle) for an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages","href":"/api-reference/servicepackages/create-a-sellable-package-bundle-for-an-offering"},{"title":"List every package for a service (storefront discovery)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/packages","href":"/api-reference/servicepackages/list-every-package-for-a-service-storefront-discovery"},{"title":"Get a package by id","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/packages/{packageId}","href":"/api-reference/servicepackages/get-a-package-by-id"},{"title":"Update a package","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/packages/{packageId}","href":"/api-reference/servicepackages/update-a-package"},{"title":"Change package status (rewrites the storefront sort key)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/packages/{packageId}/status","href":"/api-reference/servicepackages/change-package-status-rewrites-the-storefront-sort-key"}]},{"group":"Locations","pages":[{"title":"List locations for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/locations","href":"/api-reference/locations/list-locations-for-a-project"},{"title":"Get a location by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/locations/{locationId}","href":"/api-reference/locations/get-a-location-by-id"}]},{"group":"Skills","pages":[{"title":"List skills for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/skills","href":"/api-reference/skills/list-skills-for-a-project"}]},{"group":"Transactions","pages":[{"title":"Record a manual (cash/external/comp) transaction against an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/transactions","href":"/api-reference/transactions/record-a-manual-cashexternalcomp-transaction-against-an-order"},{"title":"List transactions (filter by order, client, or status)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/transactions","href":"/api-reference/transactions/list-transactions-filter-by-order-client-or-status"},{"title":"Create a Stripe PaymentIntent for an order (client-side confirmation)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/payment-intent","href":"/api-reference/transactions/create-a-stripe-paymentintent-for-an-order-client-side-confirmation"}]}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog/overview"}]}]},"basePath":"","title":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions - MarketBox API","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","CodeSnippet-D_HwgQO_.js","getApiPlaygroundDisplay-CmCoerhe.js","Page-CVJ-f_k1.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js","Markdown-CX2QY19L.js","AssistantPageLink-CY3bFglh.js","dist-Dl6_zDnT.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}