Common use cases

Build a Fully Custom Booking Flow

Copy page

Use case:
Create a complete booking system using MarketBox APIs.

Problem this solves:
Many platforms want full control over booking UX but don’t want to build complex scheduling and routing logic from scratch.

How Smart Clusters fits in:
Smart Clusters integrates with MarketBox’s broader API set (services, providers, schedules, orders), enabling teams to build a fully custom, white-labeled booking flow while offloading scheduling intelligence.

Result: Custom UX + enterprise-grade scheduling logic.

Developer guide

This guide implements the booking flow in Next.js App Router using server-only code (Route Handlers), and renders a React UI with shadcn/ui + Tailwind.

This guide assumes no payment collection inside the booking flow. If you collect payment separately (Stripe, etc.), you can store that info in your system and optionally pass it into paymentDetails later—but it is not required for this flow.

Sequence

1. List services (GET /resources/services)
2. Collect service address (Google Places Autocomplete in browser)
3. Find best provider + time slots (POST /smart-clusters/who-is-available) — server
4. Reserve the chosen slot (POST /resources/reservedslots) — server
5. Create order (confirm booking) (POST /resources/orders) — server
6. (Recommended) Cleanup on abandon (DELETE /resources/reservedslots/{reservedSlotId}) — server

MarketBox Base URL: https://api.gomarketbox.com/v1

---

Security model (non-negotiable)

• Put your API key in an env var: MARKETBOX_API_KEY.
• Only access it server-side (Next.js Route Handlers / server-only modules).
• Never send x-api-key to the browser.
• Calls from the browser should hit your Next.js endpoints, not MarketBox directly.

---

Prerequisites

Environment variables

Create .env.local:

Code
 
MARKETBOX_API_KEY=your-api-key
MARKETBOX_BASE_URL=https://api.gomarketbox.com/v1
GOOGLE_MAPS_API_KEY=your-google-key

MarketBox auth header (exact)

All server-side calls to MarketBox include:

• Header: x-api-key: your-api-key

billingId (what it is)

billingId is a UUID you choose to track your end-customer inside your own SaaS. If you are not a SaaS, you can still generate a stable UUID per customer/account in your system and reuse it in calls.

Timezone rule (exact)

Timezone is derived from the service address geolocation (lat/lng). Use a geocoding/timezone provider (commonly Google) to compute an IANA timezone string (e.g., America/Toronto) and pass it into reserved-slot creation.

Idempotency keys (required)

For these calls:

• POST /resources/reservedslots
• POST /resources/orders

You must send:

• Header: idempotency-key: <uuid>

Generate a UUID per “create” attempt, and reuse the same key when retrying the same request.

---

Project structure (App Router)

Code
 
app/
  booking/
    page.tsx                      # step container (UI)
    components/
      ServicePicker.tsx
      AddressAutocomplete.tsx
      SlotPicker.tsx
      CheckoutForm.tsx
  api/
    marketbox/
      services/route.ts            # server proxy to GET /resources/services
      who-is-available/route.ts    # server proxy to POST /smart-clusters/who-is-available
      reservedslots/route.ts       # server proxy to POST /resources/reservedslots
      orders/route.ts              # server proxy to POST /resources/orders
      reservedslots/[id]/route.ts  # server proxy to DELETE reserved slot
lib/
  marketbox/
    client.ts                      # fetch wrapper (server-only)

---

Server-only MarketBox fetch wrapper

Create lib/marketbox/client.ts:

Code
 
import "server-only";

const BASE_URL = process.env.MARKETBOX_BASE_URL ?? "https://api.gomarketbox.com/v1";
const API_KEY = process.env.MARKETBOX_API_KEY;

if (!API_KEY) throw new Error("Missing MARKETBOX_API_KEY");

export async function mbFetch(path: string, init: RequestInit = {}) {
  const headers = new Headers(init.headers);
  headers.set("x-api-key", API_KEY);

  // JSON convenience
  if (!headers.has("content-type") && init.body) {
    headers.set("content-type", "application/json");
  }

  const res = await fetch(`${BASE_URL}${path}`, {
    ...init,
    headers,
    cache: "no-store", // booking availability should not be cached
  });

  const text = await res.text();
  const data = text ? JSON.parse(text) : null;

  if (!res.ok) {
    const error = new Error(`MarketBox ${res.status} ${res.statusText}`);
    (error as any).details = data;
    throw error;
  }

  return data;
}

---

Step 1 — List services (server)

MarketBox endpoint

GET /resources/services

Next.js route handler

app/api/marketbox/services/route.ts:

Code
 
import { NextResponse } from "next/server";
import { mbFetch } from "@/lib/marketbox/client";

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const limit = searchParams.get("limit") ?? "20";
  const nextCursor = searchParams.get("nextCursor");

  const qs = new URLSearchParams({ limit });
  if (nextCursor) qs.set("nextCursor", nextCursor);

  const data = await mbFetch(`/resources/services?${qs.toString()}`, { method: "GET" });
  return NextResponse.json(data);
}

Client-side usage (booking page)

Code
 
const res = await fetch("/api/marketbox/services?limit=50");
const services = await res.json();

Response → next-request mapping

From services response	Use in next steps
data[i].id	targetServiceId in who-is-available
data[i].id	serviceId in reserved slot
data[i].id	serviceId in create order

---

Step 2 — Address Autocomplete + timezone (browser)

This runs in the browser because it’s Google UI. Collect:

• Address fields: street, city, state, country, postalCode
• latitude, longitude
• timezone (IANA): derived from lat/lng (e.g., America/Toronto)

Only send this address payload to your Next.js endpoints. Never send x-api-key.

---

Step 3 — Who-is-available (server)

MarketBox endpoint

POST /smart-clusters/who-is-available

Next.js route handler

app/api/marketbox/who-is-available/route.ts:

Code
 
import { NextResponse } from "next/server";
import { mbFetch } from "@/lib/marketbox/client";

export async function POST(req: Request) {
  const { searchParams } = new URL(req.url);
  const sortBy = searchParams.get("sortBy") ?? "leastTravelTime";
  const body = await req.json();

  const data = await mbFetch(`/smart-clusters/who-is-available?sortBy=${encodeURIComponent(sortBy)}`, {
    method: "POST",
    body: JSON.stringify(body),
  });

  return NextResponse.json(data);
}

Browser call to your server (example)

Code
 
const body = {
  billingId, // UUID you generate/store in your SaaS for this customer
  targetGeoLocation: [lat, lng],
  targetServiceId: selectedServiceId,
  bookingType: "single",
  startDateAndTime,
  endDateAndTime,
  daysOfWeek: [1,2,3,4,5],
  travelTimeType: "raw",
  minBookingNoticeMins: 60,
  preferredTimeSlotThresholdMins: 10,
  distanceUnit: "mi"
};

const res = await fetch("/api/marketbox/who-is-available?sortBy=leastTravelTime", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify(body)
});
const data = await res.json();

Response → next-request mapping

From who-is-available response	Use in next step
timeSlots[j].providerId	providerId in reserved slot
timeSlots[j].timeSlotDateAndTime	startDateAndTime in reserved slot
targetServiceId	serviceId in reserved slot + order

---

Step 4 — Reserve slot (server)

MarketBox endpoint

POST /resources/reservedslots

This guide uses serviceLocation.address (not companyLocationId).

Next.js route handler

app/api/marketbox/reservedslots/route.ts:

Code
 
import { NextResponse } from "next/server";
import { mbFetch } from "@/lib/marketbox/client";

export async function POST(req: Request) {
  const body = await req.json();

  // client should pass a UUID; if not, generate one here.
  const idempotencyKey = req.headers.get("idempotency-key") ?? crypto.randomUUID();

  const data = await mbFetch("/resources/reservedslots", {
    method: "POST",
    headers: { "idempotency-key": idempotencyKey },
    body: JSON.stringify(body),
  });

  return NextResponse.json({ ...data, idempotencyKey });
}

Browser call to your server

Code
 
const idempotencyKey = crypto.randomUUID();

const body = {
  providerId: selectedTimeSlot.providerId,
  serviceId: selectedServiceId,
  serviceLocation: {
    address: {
      street, city, state, country, postalCode,
      latitude: lat, longitude: lng
    }
  },
  timezone, // derived from the service-address lat/lng
  startDateAndTime: selectedTimeSlot.timeSlotDateAndTime,
  reservationTimeoutMins: 15
};

const res = await fetch("/api/marketbox/reservedslots", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "idempotency-key": idempotencyKey
  },
  body: JSON.stringify(body)
});

const data = await res.json();
const reservedSlotId = data.reservedSlotId;

---

Step 5 — Create order (server)

MarketBox endpoint

POST /resources/orders

No payment collection in this flow; omit paymentDetails.

Next.js route handler

app/api/marketbox/orders/route.ts:

Code
 
import { NextResponse } from "next/server";
import { mbFetch } from "@/lib/marketbox/client";

export async function POST(req: Request) {
  const body = await req.json();
  const idempotencyKey = req.headers.get("idempotency-key") ?? crypto.randomUUID();

  const data = await mbFetch("/resources/orders", {
    method: "POST",
    headers: { "idempotency-key": idempotencyKey },
    body: JSON.stringify(body),
  });

  return NextResponse.json({ ...data, idempotencyKey });
}

Browser call to your server

Code
 
const idempotencyKey = crypto.randomUUID();

const body = {
  reservedSlotId,
  serviceId: selectedServiceId,
  client: {
    firstName,
    lastName,
    email,
    phone
  }
  // Optional external IDs if you have them:
  // externalOrderId,
  // externalBookingId,
  // externalOrderData,
  // externalBookingData,
  // sendProviderEmailNotification: true
};

const res = await fetch("/api/marketbox/orders", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "idempotency-key": idempotencyKey
  },
  body: JSON.stringify(body)
});

const data = await res.json();
const booking = data.booking;
const order = data.order;

---

Step 6 — Cleanup reserved slot (server)

If checkout is abandoned, release the hold.

MarketBox endpoint

DELETE /resources/reservedslots/{reservedSlotId}

Next.js route handler

app/api/marketbox/reservedslots/[id]/route.ts:

Code
 
import { NextResponse } from "next/server";
import { mbFetch } from "@/lib/marketbox/client";

export async function DELETE(_req: Request, { params }: { params: { id: string } }) {
  const data = await mbFetch(`/resources/reservedslots/${encodeURIComponent(params.id)}`, {
    method: "DELETE",
  });
  return NextResponse.json(data);
}

Browser call

Code
 
await fetch(`/api/marketbox/reservedslots/${reservedSlotId}`, { method: "DELETE" });

---

UI implementation notes (shadcn + Tailwind)

A clean booking flow is typically 4 screens:

1. Service selection (cards or list)
2. Address input (Google Autocomplete)
3. Slot selection (provider cards + time grid/list)
4. Checkout (client details + confirm)

Use shadcn components:

• Card, Button, Input, Label
• Dialog for provider details
• Tabs or Accordion for slot lists
• Skeleton for loading results

State you’ll need in the client:

• serviceId
• address + lat/lng + timezone
• billingId
• timeSlots[] result
• selectedTimeSlot
• reservedSlotId
• client details
• order/booking confirmation

---

Appendix: Coding agent prompt (Next.js + shadcn + Tailwind)

Code
 
Build a Next.js App Router booking flow UI using shadcn/ui + Tailwind.
Do NOT call MarketBox APIs from the browser. MarketBox uses API-key auth:
send header x-api-key: your-api-key from server-side code only (env var MARKETBOX_API_KEY).
MarketBox API Open API 3.0 spec: https://docs.gomarketbox.com/api-documentation/1.0.0/mbapispec.json

Assumptions:
- billingId is a UUID the developer uses to track their own customer (SaaS end-customer). It is not a MarketBox-issued identifier.
- timezone is derived from the service address geo location (lat/lng) and passed as an IANA timezone string.
- No payment collection in this flow (omit paymentDetails).

Implement these server routes (Route Handlers) that proxy to MarketBox (base URL https://api.gomarketbox.com/v1):
- GET  /api/marketbox/services         -> GET /resources/services (support limit, nextCursor)
- POST /api/marketbox/who-is-available -> POST /smart-clusters/who-is-available?sortBy=leastTravelTime
- POST /api/marketbox/reservedslots    -> POST /resources/reservedslots (requires idempotency-key header UUID)
- POST /api/marketbox/orders           -> POST /resources/orders (requires idempotency-key header UUID)
- DELETE /api/marketbox/reservedslots/[id] -> DELETE /resources/reservedslots/{reservedSlotId}

Client-side booking page (/app/booking/page.tsx):
1) Fetch services from /api/marketbox/services and show Card list.
2) Address step: Google Places Autocomplete returns street/city/state/country/postalCode + latitude/longitude.
   Use geo->timezone lookup to get IANA timezone string (e.g., America/Toronto).
3) Call /api/marketbox/who-is-available with body fields:
   billingId, targetGeoLocation [lat,lng], targetServiceId, plus optional startDateAndTime/endDateAndTime/daysOfWeek.
   Render provider cards + time slots from response timeSlots[].
4) On slot select:
   Call /api/marketbox/reservedslots with body:
   providerId, serviceId, serviceLocation.address{street,city,state,country,postalCode,latitude,longitude},
   timezone, startDateAndTime, reservationTimeoutMins.
   Send idempotency-key header from the browser to your server route (server forwards it).
   Save reservedSlotId from response.
5) Checkout form (shadcn Input):
   Collect client{firstName,lastName,email,phone}. On confirm:
   Call /api/marketbox/orders with body reservedSlotId, serviceId, client (omit paymentDetails).
   Send idempotency-key header UUID.
6) If user cancels/abandons after reserving, call DELETE /api/marketbox/reservedslots/[reservedSlotId].

Deliver:
- file structure
- server-only fetch wrapper using env vars (x-api-key: your-api-key)
- React components using shadcn + Tailwind
- clear response->next-request variable wiring