Convert a hold into confirmed bookings (the idempotent purchase hook)
curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"orderId": "ord_01kv7n10k0fnptwk81wkm59vj7",
"orderItemId": "oi_01kv7n10k0fnptwk81wkm59vj7",
"heldBy": "<string>",
"atomicity": "all_or_nothing"
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert"
payload = {
"orderId": "ord_01kv7n10k0fnptwk81wkm59vj7",
"orderItemId": "oi_01kv7n10k0fnptwk81wkm59vj7",
"heldBy": "<string>",
"atomicity": "all_or_nothing"
}
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({
orderId: 'ord_01kv7n10k0fnptwk81wkm59vj7',
orderItemId: 'oi_01kv7n10k0fnptwk81wkm59vj7',
heldBy: '<string>',
atomicity: 'all_or_nothing'
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert', 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}/holds/{reservationId}/convert",
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([
'orderId' => 'ord_01kv7n10k0fnptwk81wkm59vj7',
'orderItemId' => 'oi_01kv7n10k0fnptwk81wkm59vj7',
'heldBy' => '<string>',
'atomicity' => 'all_or_nothing'
]),
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}/holds/{reservationId}/convert"
payload := strings.NewReader("{\n \"orderId\": \"ord_01kv7n10k0fnptwk81wkm59vj7\",\n \"orderItemId\": \"oi_01kv7n10k0fnptwk81wkm59vj7\",\n \"heldBy\": \"<string>\",\n \"atomicity\": \"all_or_nothing\"\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}/holds/{reservationId}/convert")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"orderId\": \"ord_01kv7n10k0fnptwk81wkm59vj7\",\n \"orderItemId\": \"oi_01kv7n10k0fnptwk81wkm59vj7\",\n \"heldBy\": \"<string>\",\n \"atomicity\": \"all_or_nothing\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert")
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 \"orderId\": \"ord_01kv7n10k0fnptwk81wkm59vj7\",\n \"orderItemId\": \"oi_01kv7n10k0fnptwk81wkm59vj7\",\n \"heldBy\": \"<string>\",\n \"atomicity\": \"all_or_nothing\"\n}"
response = http.request(request)
puts response.read_body{
"orderId": "<string>",
"orderItemId": "<string>",
"packageOrderItemId": "<string>",
"atomicity": "all_or_nothing",
"created": [
{
"sessionIndex": 1,
"bookingId": "<string>",
"allocationId": "<string>"
}
],
"failed": [
{
"sessionIndex": 1,
"reason": "<string>"
}
],
"quantityRemaining": 1
}{
"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"
}{
"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"
}Holds
Convert a hold into confirmed bookings (the idempotent purchase hook)
Turns the held supplier time into real bookings, drawing credits from the given order item. The order item's skuType decides what is booked: a PACKAGE item books every held interval as package sessions; a SINGLE_SESSION item books the ONE held interval as an ordinary single booking — no package, and no 1-credit "reservation vehicle" package needed. (A SINGLE_SESSION item against a hold covering more than one interval returns 409 RESERVATION_MULTI_INTERVAL; any other skuType returns 400.) Call it once your checkout has confirmed payment (poll `GET /orders/{orderId}` for `PAID`, or convert first: convert does not require a paid order). The open API sends no webhooks. It is idempotent on the reservationId (the package booking write uses the deterministic key convert:<reservationId>), so a retried call replays the same bookings rather than double-booking, and a reservation already CONVERTED replays its stored result. The bookings are rebuilt from the RESERVATION and the ORDER ITEM — never by re-resolving a suggestion that may have expired — so the booked service and the credit it draws down cannot disagree. Returns 409 HOLD_EXPIRED if you converted too late (the hold no longer blocks anyone), or SLOT_HELD/SLOT_BOOKED if someone else took the time in the meantime. The order need not be paid, but a CANCELLED order converts nothing (409 ORDER_CANCELLED), not even as a replay: its cascade has released its credits and cancelled what it had booked. This response is NOT wrapped in a { data } envelope, and created[].sessionIndex is 0-based.
POST
/
v1
/
projects
/
{projectId}
/
holds
/
{reservationId}
/
convert
Convert a hold into confirmed bookings (the idempotent purchase hook)
curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"orderId": "ord_01kv7n10k0fnptwk81wkm59vj7",
"orderItemId": "oi_01kv7n10k0fnptwk81wkm59vj7",
"heldBy": "<string>",
"atomicity": "all_or_nothing"
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert"
payload = {
"orderId": "ord_01kv7n10k0fnptwk81wkm59vj7",
"orderItemId": "oi_01kv7n10k0fnptwk81wkm59vj7",
"heldBy": "<string>",
"atomicity": "all_or_nothing"
}
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({
orderId: 'ord_01kv7n10k0fnptwk81wkm59vj7',
orderItemId: 'oi_01kv7n10k0fnptwk81wkm59vj7',
heldBy: '<string>',
atomicity: 'all_or_nothing'
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert', 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}/holds/{reservationId}/convert",
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([
'orderId' => 'ord_01kv7n10k0fnptwk81wkm59vj7',
'orderItemId' => 'oi_01kv7n10k0fnptwk81wkm59vj7',
'heldBy' => '<string>',
'atomicity' => 'all_or_nothing'
]),
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}/holds/{reservationId}/convert"
payload := strings.NewReader("{\n \"orderId\": \"ord_01kv7n10k0fnptwk81wkm59vj7\",\n \"orderItemId\": \"oi_01kv7n10k0fnptwk81wkm59vj7\",\n \"heldBy\": \"<string>\",\n \"atomicity\": \"all_or_nothing\"\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}/holds/{reservationId}/convert")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"orderId\": \"ord_01kv7n10k0fnptwk81wkm59vj7\",\n \"orderItemId\": \"oi_01kv7n10k0fnptwk81wkm59vj7\",\n \"heldBy\": \"<string>\",\n \"atomicity\": \"all_or_nothing\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/holds/{reservationId}/convert")
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 \"orderId\": \"ord_01kv7n10k0fnptwk81wkm59vj7\",\n \"orderItemId\": \"oi_01kv7n10k0fnptwk81wkm59vj7\",\n \"heldBy\": \"<string>\",\n \"atomicity\": \"all_or_nothing\"\n}"
response = http.request(request)
puts response.read_body{
"orderId": "<string>",
"orderItemId": "<string>",
"packageOrderItemId": "<string>",
"atomicity": "all_or_nothing",
"created": [
{
"sessionIndex": 1,
"bookingId": "<string>",
"allocationId": "<string>"
}
],
"failed": [
{
"sessionIndex": 1,
"reason": "<string>"
}
],
"quantityRemaining": 1
}{
"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"
}{
"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
application/json
orderId + orderItemId (+ optional heldBy, atomicity)
Response
Hold converted to confirmed bookings