curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"serviceId": "srv_01kq8cp17bf03t125zhakpcgyx",
"locationId": "<string>",
"lat": 43.6532,
"lng": -79.3832,
"supplierId": "<string>",
"timezone": "<string>",
"rrule": "FREQ=WEEKLY;BYDAY=MO",
"lookAheadStartDate": "2026-07-09T00:00:00-04:00",
"preferredTimes": [
{
"startTime": "<string>",
"endTime": "<string>"
}
],
"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
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options"
payload = {
"serviceId": "srv_01kq8cp17bf03t125zhakpcgyx",
"locationId": "<string>",
"lat": 43.6532,
"lng": -79.3832,
"supplierId": "<string>",
"timezone": "<string>",
"rrule": "FREQ=WEEKLY;BYDAY=MO",
"lookAheadStartDate": "2026-07-09T00:00:00-04:00",
"preferredTimes": [
{
"startTime": "<string>",
"endTime": "<string>"
}
],
"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
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
serviceId: 'srv_01kq8cp17bf03t125zhakpcgyx',
locationId: '<string>',
lat: 43.6532,
lng: -79.3832,
supplierId: '<string>',
timezone: '<string>',
rrule: 'FREQ=WEEKLY;BYDAY=MO',
lookAheadStartDate: '2026-07-09T00:00:00-04:00',
preferredTimes: [{startTime: '<string>', endTime: '<string>'}],
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
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'serviceId' => 'srv_01kq8cp17bf03t125zhakpcgyx',
'locationId' => '<string>',
'lat' => 43.6532,
'lng' => -79.3832,
'supplierId' => '<string>',
'timezone' => '<string>',
'rrule' => 'FREQ=WEEKLY;BYDAY=MO',
'lookAheadStartDate' => '2026-07-09T00:00:00-04:00',
'preferredTimes' => [
[
'startTime' => '<string>',
'endTime' => '<string>'
]
],
'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
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options"
payload := strings.NewReader("{\n \"serviceId\": \"srv_01kq8cp17bf03t125zhakpcgyx\",\n \"locationId\": \"<string>\",\n \"lat\": 43.6532,\n \"lng\": -79.3832,\n \"supplierId\": \"<string>\",\n \"timezone\": \"<string>\",\n \"rrule\": \"FREQ=WEEKLY;BYDAY=MO\",\n \"lookAheadStartDate\": \"2026-07-09T00:00:00-04:00\",\n \"preferredTimes\": [\n {\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n }\n ],\n \"daysOfWeek\": [\n 1,\n 2\n ],\n \"excludeDates\": [\n \"2026-08-20\",\n \"2026-08-21\",\n \"2026-08-22\"\n ],\n \"sessionsPerWeek\": 3,\n \"cadenceFlexibility\": \"FALLBACK\",\n \"guaranteeSlate\": true,\n \"maxCadenceAlternatives\": 3,\n \"allowWeekdaySubstitution\": true,\n \"minGapDays\": 2,\n \"maxSessionsPerWeek\": 3,\n \"maxAlternates\": 3,\n \"persist\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"serviceId\": \"srv_01kq8cp17bf03t125zhakpcgyx\",\n \"locationId\": \"<string>\",\n \"lat\": 43.6532,\n \"lng\": -79.3832,\n \"supplierId\": \"<string>\",\n \"timezone\": \"<string>\",\n \"rrule\": \"FREQ=WEEKLY;BYDAY=MO\",\n \"lookAheadStartDate\": \"2026-07-09T00:00:00-04:00\",\n \"preferredTimes\": [\n {\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n }\n ],\n \"daysOfWeek\": [\n 1,\n 2\n ],\n \"excludeDates\": [\n \"2026-08-20\",\n \"2026-08-21\",\n \"2026-08-22\"\n ],\n \"sessionsPerWeek\": 3,\n \"cadenceFlexibility\": \"FALLBACK\",\n \"guaranteeSlate\": true,\n \"maxCadenceAlternatives\": 3,\n \"allowWeekdaySubstitution\": true,\n \"minGapDays\": 2,\n \"maxSessionsPerWeek\": 3,\n \"maxAlternates\": 3,\n \"persist\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"serviceId\": \"srv_01kq8cp17bf03t125zhakpcgyx\",\n \"locationId\": \"<string>\",\n \"lat\": 43.6532,\n \"lng\": -79.3832,\n \"supplierId\": \"<string>\",\n \"timezone\": \"<string>\",\n \"rrule\": \"FREQ=WEEKLY;BYDAY=MO\",\n \"lookAheadStartDate\": \"2026-07-09T00:00:00-04:00\",\n \"preferredTimes\": [\n {\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n }\n ],\n \"daysOfWeek\": [\n 1,\n 2\n ],\n \"excludeDates\": [\n \"2026-08-20\",\n \"2026-08-21\",\n \"2026-08-22\"\n ],\n \"sessionsPerWeek\": 3,\n \"cadenceFlexibility\": \"FALLBACK\",\n \"guaranteeSlate\": true,\n \"maxCadenceAlternatives\": 3,\n \"allowWeekdaySubstitution\": true,\n \"minGapDays\": 2,\n \"maxSessionsPerWeek\": 3,\n \"maxAlternates\": 3,\n \"persist\": true\n}"
response = http.request(request)
puts response.read_body{
"searchId": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n",
"data": [
{
"package": {
"entityType": "SERVICE_PACKAGE",
"projectId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"packageId": "<string>",
"pricingModel": "PER_SESSION",
"pricing": [
{
"ruleId": "<string>",
"scope": "DEFAULT",
"price": {
"amount": 1,
"currency": "<string>"
},
"country": "<string>",
"state": "<string>",
"postalCodes": [
"<string>"
],
"tax": {
"taxable": true,
"taxPercentage": 1
}
}
],
"creditCount": 1,
"validityDays": 1,
"status": "DRAFT",
"capacity": 1,
"deleted": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"updatedBy": "<string>",
"name": {},
"description": {},
"discountPercent": 50
},
"status": "OK",
"reason": "<string>",
"slateId": "<string>",
"primarySlate": {
"slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
"supplierId": "<string>",
"completeness": "COMPLETE",
"sessionsRequested": 1,
"sessionsFilled": 1,
"startTimeConsistencyPercent": 50,
"totalTravelTimeMins": 1,
"slots": [
{
"slotId": "<string>",
"sessionIndex": 1,
"supplierId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"bookingStartUtc": "2023-11-07T05:31:56Z",
"bookingEndUtc": "2023-11-07T05:31:56Z",
"bookingTz": "<string>",
"locationType": "PHYSICAL",
"locationId": "<string>",
"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": "<string>",
"completeness": "COMPLETE",
"sessionsRequested": 1,
"sessionsFilled": 1,
"startTimeConsistencyPercent": 50,
"totalTravelTimeMins": 1,
"slots": [
{
"slotId": "<string>",
"sessionIndex": 1,
"supplierId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"bookingStartUtc": "2023-11-07T05:31:56Z",
"bookingEndUtc": "2023-11-07T05:31:56Z",
"bookingTz": "<string>",
"locationType": "PHYSICAL",
"locationId": "<string>",
"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": "<string>",
"completeness": "COMPLETE",
"sessionsRequested": 1,
"sessionsFilled": 1,
"startTimeConsistencyPercent": 50,
"totalTravelTimeMins": 1,
"slots": [
{
"slotId": "<string>",
"sessionIndex": 1,
"supplierId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"bookingStartUtc": "2023-11-07T05:31:56Z",
"bookingEndUtc": "2023-11-07T05:31:56Z",
"bookingTz": "<string>",
"locationType": "PHYSICAL",
"locationId": "<string>",
"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
}
},
"cadenceAlternatives": []
}
]
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}List a service's packages, each with a ready-to-book slate
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//package-bookings. Cadence defaults to FREQ=WEEKLY;COUNT=, 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.
The 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.
The 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).
curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"serviceId": "srv_01kq8cp17bf03t125zhakpcgyx",
"locationId": "<string>",
"lat": 43.6532,
"lng": -79.3832,
"supplierId": "<string>",
"timezone": "<string>",
"rrule": "FREQ=WEEKLY;BYDAY=MO",
"lookAheadStartDate": "2026-07-09T00:00:00-04:00",
"preferredTimes": [
{
"startTime": "<string>",
"endTime": "<string>"
}
],
"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
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options"
payload = {
"serviceId": "srv_01kq8cp17bf03t125zhakpcgyx",
"locationId": "<string>",
"lat": 43.6532,
"lng": -79.3832,
"supplierId": "<string>",
"timezone": "<string>",
"rrule": "FREQ=WEEKLY;BYDAY=MO",
"lookAheadStartDate": "2026-07-09T00:00:00-04:00",
"preferredTimes": [
{
"startTime": "<string>",
"endTime": "<string>"
}
],
"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
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
serviceId: 'srv_01kq8cp17bf03t125zhakpcgyx',
locationId: '<string>',
lat: 43.6532,
lng: -79.3832,
supplierId: '<string>',
timezone: '<string>',
rrule: 'FREQ=WEEKLY;BYDAY=MO',
lookAheadStartDate: '2026-07-09T00:00:00-04:00',
preferredTimes: [{startTime: '<string>', endTime: '<string>'}],
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
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'serviceId' => 'srv_01kq8cp17bf03t125zhakpcgyx',
'locationId' => '<string>',
'lat' => 43.6532,
'lng' => -79.3832,
'supplierId' => '<string>',
'timezone' => '<string>',
'rrule' => 'FREQ=WEEKLY;BYDAY=MO',
'lookAheadStartDate' => '2026-07-09T00:00:00-04:00',
'preferredTimes' => [
[
'startTime' => '<string>',
'endTime' => '<string>'
]
],
'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
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options"
payload := strings.NewReader("{\n \"serviceId\": \"srv_01kq8cp17bf03t125zhakpcgyx\",\n \"locationId\": \"<string>\",\n \"lat\": 43.6532,\n \"lng\": -79.3832,\n \"supplierId\": \"<string>\",\n \"timezone\": \"<string>\",\n \"rrule\": \"FREQ=WEEKLY;BYDAY=MO\",\n \"lookAheadStartDate\": \"2026-07-09T00:00:00-04:00\",\n \"preferredTimes\": [\n {\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n }\n ],\n \"daysOfWeek\": [\n 1,\n 2\n ],\n \"excludeDates\": [\n \"2026-08-20\",\n \"2026-08-21\",\n \"2026-08-22\"\n ],\n \"sessionsPerWeek\": 3,\n \"cadenceFlexibility\": \"FALLBACK\",\n \"guaranteeSlate\": true,\n \"maxCadenceAlternatives\": 3,\n \"allowWeekdaySubstitution\": true,\n \"minGapDays\": 2,\n \"maxSessionsPerWeek\": 3,\n \"maxAlternates\": 3,\n \"persist\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"serviceId\": \"srv_01kq8cp17bf03t125zhakpcgyx\",\n \"locationId\": \"<string>\",\n \"lat\": 43.6532,\n \"lng\": -79.3832,\n \"supplierId\": \"<string>\",\n \"timezone\": \"<string>\",\n \"rrule\": \"FREQ=WEEKLY;BYDAY=MO\",\n \"lookAheadStartDate\": \"2026-07-09T00:00:00-04:00\",\n \"preferredTimes\": [\n {\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n }\n ],\n \"daysOfWeek\": [\n 1,\n 2\n ],\n \"excludeDates\": [\n \"2026-08-20\",\n \"2026-08-21\",\n \"2026-08-22\"\n ],\n \"sessionsPerWeek\": 3,\n \"cadenceFlexibility\": \"FALLBACK\",\n \"guaranteeSlate\": true,\n \"maxCadenceAlternatives\": 3,\n \"allowWeekdaySubstitution\": true,\n \"minGapDays\": 2,\n \"maxSessionsPerWeek\": 3,\n \"maxAlternates\": 3,\n \"persist\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/package-options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"serviceId\": \"srv_01kq8cp17bf03t125zhakpcgyx\",\n \"locationId\": \"<string>\",\n \"lat\": 43.6532,\n \"lng\": -79.3832,\n \"supplierId\": \"<string>\",\n \"timezone\": \"<string>\",\n \"rrule\": \"FREQ=WEEKLY;BYDAY=MO\",\n \"lookAheadStartDate\": \"2026-07-09T00:00:00-04:00\",\n \"preferredTimes\": [\n {\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n }\n ],\n \"daysOfWeek\": [\n 1,\n 2\n ],\n \"excludeDates\": [\n \"2026-08-20\",\n \"2026-08-21\",\n \"2026-08-22\"\n ],\n \"sessionsPerWeek\": 3,\n \"cadenceFlexibility\": \"FALLBACK\",\n \"guaranteeSlate\": true,\n \"maxCadenceAlternatives\": 3,\n \"allowWeekdaySubstitution\": true,\n \"minGapDays\": 2,\n \"maxSessionsPerWeek\": 3,\n \"maxAlternates\": 3,\n \"persist\": true\n}"
response = http.request(request)
puts response.read_body{
"searchId": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n",
"data": [
{
"package": {
"entityType": "SERVICE_PACKAGE",
"projectId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"packageId": "<string>",
"pricingModel": "PER_SESSION",
"pricing": [
{
"ruleId": "<string>",
"scope": "DEFAULT",
"price": {
"amount": 1,
"currency": "<string>"
},
"country": "<string>",
"state": "<string>",
"postalCodes": [
"<string>"
],
"tax": {
"taxable": true,
"taxPercentage": 1
}
}
],
"creditCount": 1,
"validityDays": 1,
"status": "DRAFT",
"capacity": 1,
"deleted": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"updatedBy": "<string>",
"name": {},
"description": {},
"discountPercent": 50
},
"status": "OK",
"reason": "<string>",
"slateId": "<string>",
"primarySlate": {
"slateId": "slate_01kx16ejsqffc9rbgdcc591w2p",
"supplierId": "<string>",
"completeness": "COMPLETE",
"sessionsRequested": 1,
"sessionsFilled": 1,
"startTimeConsistencyPercent": 50,
"totalTravelTimeMins": 1,
"slots": [
{
"slotId": "<string>",
"sessionIndex": 1,
"supplierId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"bookingStartUtc": "2023-11-07T05:31:56Z",
"bookingEndUtc": "2023-11-07T05:31:56Z",
"bookingTz": "<string>",
"locationType": "PHYSICAL",
"locationId": "<string>",
"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": "<string>",
"completeness": "COMPLETE",
"sessionsRequested": 1,
"sessionsFilled": 1,
"startTimeConsistencyPercent": 50,
"totalTravelTimeMins": 1,
"slots": [
{
"slotId": "<string>",
"sessionIndex": 1,
"supplierId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"bookingStartUtc": "2023-11-07T05:31:56Z",
"bookingEndUtc": "2023-11-07T05:31:56Z",
"bookingTz": "<string>",
"locationType": "PHYSICAL",
"locationId": "<string>",
"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": "<string>",
"completeness": "COMPLETE",
"sessionsRequested": 1,
"sessionsFilled": 1,
"startTimeConsistencyPercent": 50,
"totalTravelTimeMins": 1,
"slots": [
{
"slotId": "<string>",
"sessionIndex": 1,
"supplierId": "<string>",
"serviceId": "<string>",
"offeringId": "<string>",
"bookingStartUtc": "2023-11-07T05:31:56Z",
"bookingEndUtc": "2023-11-07T05:31:56Z",
"bookingTz": "<string>",
"locationType": "PHYSICAL",
"locationId": "<string>",
"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
}
},
"cadenceAlternatives": []
}
]
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}Authorizations
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
Body
Service + location + optional supplier and cadence
A service + a location (+ optionally a supplier and cadence).
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.
1 - 7 elements0 <= x <= 6[1, 2]
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.
90^\d{4}-\d{2}-\d{2}$["2026-08-20", "2026-08-21", "2026-08-22"]
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.
1 <= x <= 143
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".
NONE, FALLBACK, ALWAYS "FALLBACK"
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.
true
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.
0 <= x <= 902
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.
0 < x <= 143
Response
One entry per ACTIVE package
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.
"srch_01k7q3x9h4e8rb2d6m0z5a7c1n"